@plebeiantech/lat.md 0.12.3-fork.9 → 0.13.4-fork.2

package/dist/src/cli/check-mode.js

@@ -1,364 +0,0 @@
-import { readFile } from 'node:fs/promises';
-import { basename, dirname, join, relative } from 'node:path';
-import { listLatticeFiles, parseFrontmatter } from '../lattice.js';
-import { parse } from '../parser.js';
-import { quoteUntrusted } from '../untrusted.js';
-import { toPosix } from '../walk.js';
-export const DIATAXIS_MODES = [
-    'tutorial',
-    'how-to',
-    'reference',
-    'explanation',
-];
-/** Directory below lat.md/ that holds each mode. */
-export const MODE_DIRS = {
-    tutorial: 'tutorials',
-    'how-to': 'how-to',
-    reference: 'reference',
-    explanation: 'explanation',
-};
-/** Reverse lookup: first path segment -> mode. Built once, not per file. */
-// Null-prototype: the key is a directory name read off disk.
-const DIR_TO_MODE = Object.create(null);
-for (const mode of DIATAXIS_MODES) {
-    DIR_TO_MODE[MODE_DIRS[mode]] = mode;
-}
-const OUTCOME_RE = /\b(outcome|by the end|you will (build|learn|have|create)|what you (will )?(build|learn|have|create))\b/i;
-/**
- * Imperative verbs that flag a command inside an explanation document.
- * Deliberately excludes ambiguous verbs (Use, Go, Make, Type, Enter, Call,
- * Import, Export) — each reads naturally as a noun or as descriptive prose
- * at the start of a sentence ("Use cases include...", "Type inference..."),
- * and including them produced false positives in testing.
- */
-const IMPERATIVE_VERBS = [
-    'Run',
-    'Install',
-    'Add',
-    'Set',
-    'Open',
-    'Create',
-    'Delete',
-    'Edit',
-    'Copy',
-    'Move',
-    'Click',
-    'Press',
-    'Configure',
-    'Update',
-    'Remove',
-    'Execute',
-    'Choose',
-    'Select',
-    'Replace',
-    'Rename',
-    'Restart',
-    'Deploy',
-];
-const MAX_IMPERATIVE_ERRORS = 10;
-function orderedListPresent(tree) {
-    let found = false;
-    const walk = (nodes) => {
-        for (const node of nodes) {
-            if (node.type === 'list' && node.ordered === true) {
-                found = true;
-                return;
-            }
-            if ('children' in node) {
-                walk(node.children);
-            }
-            if (found)
-                return;
-        }
-    };
-    walk(tree.children);
-    return found;
-}
-function outcomeStated(tree) {
-    for (const node of tree.children) {
-        if (node.type === 'heading' || node.type === 'paragraph') {
-            const text = inlineTextOf(node);
-            if (OUTCOME_RE.test(text))
-                return true;
-        }
-    }
-    return false;
-}
-function inlineTextOf(node) {
-    return node.children
-        .map((c) => {
-        if ('value' in c && typeof c.value === 'string')
-            return c.value;
-        if ('children' in c)
-            return inlineTextOf(c);
-        return '';
-    })
-        .join('');
-}
-/**
- * Extra top-level paragraphs found under headings, beyond the one
- * `checkSections` already permits as the leading summary. A paragraph
- * before the first heading is the document lead, not narrative prose.
- */
-function extraParagraphs(tree) {
-    const offenders = [];
-    let currentHeading = null;
-    let seenParagraphUnderHeading = false;
-    for (const node of tree.children) {
-        if (node.type === 'heading') {
-            currentHeading = inlineTextOf(node);
-            seenParagraphUnderHeading = false;
-            continue;
-        }
-        if (node.type === 'paragraph') {
-            if (currentHeading === null) {
-                // Document lead paragraph before any heading — allowed.
-                continue;
-            }
-            if (!seenParagraphUnderHeading) {
-                seenParagraphUnderHeading = true;
-            }
-            else {
-                offenders.push({
-                    line: node.position.start.line,
-                    heading: currentHeading,
-                });
-            }
-        }
-    }
-    return offenders;
-}
-/**
- * Line numbers (1-indexed, inclusive of both ends) that belong to a `code`
- * or `yaml` (frontmatter) node anywhere in the tree. Walking the parsed tree
- * — rather than re-scanning raw text with a fence regex — means a fence of
- * any marker length or an indented code block is recognized correctly, and
- * frontmatter needs no special case: it simply isn't prose in the tree.
- */
-function nonProseLines(tree) {
-    const lines = new Set();
-    const markRange = (node) => {
-        if (!node.position)
-            return;
-        for (let line = node.position.start.line; line <= node.position.end.line; line++) {
-            lines.add(line);
-        }
-    };
-    const walk = (nodes) => {
-        for (const node of nodes) {
-            if (node.type === 'code' || node.type === 'yaml') {
-                markRange(node);
-                continue;
-            }
-            if ('children' in node) {
-                walk(node.children);
-            }
-        }
-    };
-    walk(tree.children);
-    return lines;
-}
-function findImperativeHits(tree, content) {
-    const hits = [];
-    const lines = content.split('\n');
-    const skipLines = nonProseLines(tree);
-    for (let i = 0; i < lines.length; i++) {
-        const lineNumber = i + 1;
-        if (skipLines.has(lineNumber))
-            continue;
-        const trimmedStart = lines[i].trimStart();
-        if (trimmedStart.startsWith('#'))
-            continue;
-        let text = trimmedStart;
-        text = text.replace(/^(?:[-*+]\s+|\d+[.)]\s+)/, '');
-        text = text.replace(/^\*\*/, '');
-        for (const verb of IMPERATIVE_VERBS) {
-            if (text.startsWith(verb + ' ')) {
-                hits.push({ line: lineNumber, verb });
-                break;
-            }
-        }
-    }
-    return hits;
-}
-/**
- * The index file a directory is required to carry, e.g. `lat.md` for the root
- * and `reference.md` for `reference/`. An index is navigation rather than
- * content, so the `require-mode` gate below never asks one to declare a mode.
- */
-export function indexNameFor(dirName) {
-    return dirName.endsWith('.md') ? dirName : dirName + '.md';
-}
-/**
- * What the root index says about the mode requirement.
- *
- * Opt-in, and deliberately read from the tree rather than from a flag or an
- * environment variable: the rule belongs to a documentation set, not to a
- * machine or a CI job, and a tree that predates the rule has to keep passing.
- * `lat init` stamps the flag into the root index it scaffolds, so a project
- * set up after this exists is gated from its first commit while an older one
- * is untouched until someone adds the line.
- *
- * The raw value is returned rather than a boolean so the caller can tell an
- * absent flag from one that was set to something this never reads. `yes` and
- * `1` are strings to a YAML 1.2 parser, and enforcing nothing on them while
- * saying nothing about them is how a project ends up believing the gate is on.
- */
-async function readRequireModeFlag(latticeDir) {
-    const indexPath = join(latticeDir, indexNameFor(basename(latticeDir)));
-    try {
-        const content = await readFile(indexPath, 'utf-8');
-        return parseFrontmatter(content).raw['require-mode'];
-    }
-    catch {
-        return undefined;
-    }
-}
-export async function checkMode(latticeDir, projectRoot = dirname(latticeDir), options = {}) {
-    const files = await listLatticeFiles(latticeDir);
-    const errors = [];
-    const flag = await readRequireModeFlag(latticeDir);
-    const requireMode = options.requireMode ?? flag === true;
-    if (flag !== undefined && typeof flag !== 'boolean') {
-        const indexPath = join(latticeDir, indexNameFor(basename(latticeDir)));
-        errors.push({
-            file: relative(process.cwd(), indexPath),
-            line: 1,
-            target: toPosix(relative(projectRoot, indexPath)).replace(/\.md$/, ''),
-            message: `require-mode is ${JSON.stringify(flag)} — it must be true or false.\n    Anything else is enforced as off, so the gate this line looks like it turns on is not running.`,
-        });
-    }
-    for (const file of files) {
-        const content = await readFile(file, 'utf-8');
-        const relPath = relative(process.cwd(), file);
-        const target = toPosix(relative(projectRoot, file)).replace(/\.md$/, '');
-        const fm = parseFrontmatter(content);
-        const declaredRaw = fm.raw['mode'];
-        // null (bare `mode:` key) is treated as absent; any other non-string is
-        // reported below via declaredNonString.
-        const declared = declaredRaw === null || declaredRaw === undefined
-            ? undefined
-            : typeof declaredRaw === 'string'
-                ? declaredRaw
-                : undefined;
-        const declaredNonString = declaredRaw !== null &&
-            declaredRaw !== undefined &&
-            typeof declaredRaw !== 'string'
-            ? declaredRaw
-            : undefined;
-        const relFromLattice = toPosix(relative(latticeDir, file));
-        const firstSegment = relFromLattice.split('/')[0];
-        const dirMode = firstSegment && firstSegment !== relFromLattice
-            ? DIR_TO_MODE[firstSegment]
-            : undefined;
-        if (declaredNonString !== undefined) {
-            errors.push({
-                file: relPath,
-                line: 1,
-                target,
-                message: `document declares unknown mode ${quoteUntrusted(JSON.stringify(declaredNonString), 40)} — use one of: tutorial, how-to, reference, explanation`,
-            });
-            continue;
-        }
-        if (declared !== undefined &&
-            !DIATAXIS_MODES.includes(declared)) {
-            errors.push({
-                file: relPath,
-                line: 1,
-                target,
-                message: `document declares unknown mode ${quoteUntrusted(declared, 40)} — use one of: tutorial, how-to, reference, explanation`,
-            });
-            continue;
-        }
-        if (declared !== undefined &&
-            dirMode !== undefined &&
-            declared !== dirMode) {
-            errors.push({
-                file: relPath,
-                line: 1,
-                target,
-                message: `document is in lat.md/${firstSegment}/ but declares mode: ${declared} — the mode must match the directory that holds it`,
-            });
-            continue;
-        }
-        const mode = (declared ?? dirMode);
-        if (mode === undefined) {
-            const segments = relFromLattice.split('/');
-            const fileName = segments.pop();
-            const holder = segments.length === 0 ? basename(latticeDir) : segments.at(-1);
-            const isIndex = fileName === indexNameFor(holder);
-            if (requireMode && !isIndex) {
-                errors.push({
-                    file: relPath,
-                    line: 1,
-                    target,
-                    message: 'document declares no Diátaxis mode and is not in a mode directory — move it under lat.md/tutorials/, lat.md/how-to/, lat.md/reference/ or lat.md/explanation/, or declare one under its `lat:` frontmatter.\n    A document that would fail its mode is usually two documents: the lookup half belongs in reference/, the reasoning half in explanation/.\n    (The root index sets require-mode: true. Remove that line to turn this off.)',
-                });
-            }
-            continue;
-        }
-        const tree = parse(content);
-        if (mode === 'how-to') {
-            if (!orderedListPresent(tree)) {
-                errors.push({
-                    file: relPath,
-                    line: 1,
-                    target,
-                    message: `a how-to must give ordered steps — add a numbered list`,
-                });
-            }
-            continue;
-        }
-        if (mode === 'tutorial') {
-            if (!orderedListPresent(tree)) {
-                errors.push({
-                    file: relPath,
-                    line: 1,
-                    target,
-                    message: `a tutorial must give ordered steps — add a numbered list`,
-                });
-            }
-            if (!outcomeStated(tree)) {
-                errors.push({
-                    file: relPath,
-                    line: 1,
-                    target,
-                    message: `a tutorial must state its outcome — add a heading or sentence saying what the reader will have at the end`,
-                });
-            }
-            continue;
-        }
-        if (mode === 'reference') {
-            for (const offender of extraParagraphs(tree)) {
-                errors.push({
-                    file: relPath,
-                    line: offender.line,
-                    target,
-                    message: `a reference must not contain narrative prose — this is a second paragraph under "${offender.heading}"; use a list, a table, or a code block instead`,
-                });
-            }
-            continue;
-        }
-        if (mode === 'explanation') {
-            const hits = findImperativeHits(tree, content);
-            const capped = hits.slice(0, MAX_IMPERATIVE_ERRORS);
-            for (const hit of capped) {
-                errors.push({
-                    file: relPath,
-                    line: hit.line,
-                    target,
-                    message: `an explanation must not give commands — line starts with the imperative "${hit.verb}"; describe what happens instead, or move this to a how-to`,
-                });
-            }
-            if (hits.length > MAX_IMPERATIVE_ERRORS) {
-                errors.push({
-                    file: relPath,
-                    line: 1,
-                    target,
-                    message: `capped at ${MAX_IMPERATIVE_ERRORS} imperative-command errors for this document — fix these first, then re-run`,
-                });
-            }
-        }
-    }
-    return errors;
-}

package/dist/src/cli/check-status.d.ts

@@ -1,74 +0,0 @@
-import type { Styler } from '../context.js';
-import type { CheckError } from './check.js';
-/**
- * Who wrote a document, and whether a person has checked it.
- *
- * lat.md states that agents write the graph. Without this field an unmarked
- * claim written by an agent reaches the model carrying exactly the authority
- * of one a person read and approved.
- */
-export declare const DOC_STATUSES: readonly ["human-reviewed", "agent-extracted"];
-export type DocStatus = (typeof DOC_STATUSES)[number];
-export type DocProvenance = {
-    /** Raw `status` value, which may not be one this build understands. */
-    status?: string;
-    /** Raw `reviewed-hash` value, which may not be hex. */
-    reviewedHash?: string;
-};
-/**
- * Read the provenance fields out of a document's frontmatter.
- *
- * Fields live under the top-level `lat:` mapping, so they are read off
- * `LatFrontmatter.raw` rather than being promoted to named fields. Adding a
- * named field would mean editing `parseFrontmatter`, and keeping that function
- * closed to per-feature edits is the whole reason `raw` exists.
- */
-export declare function readProvenance(content: string): DocProvenance;
-/**
- * Hash the prose a review actually covered.
- *
- * A plain `status` field becomes a lie the moment an agent edits the document:
- * the field still says a person checked the text, but the text is no longer
- * the text that person read. Capturing the content at review time turns that
- * silent failure into a check.
- *
- * Frontmatter is excluded deliberately: adding an unrelated frontmatter key
- * does not change a single claim in the prose, and invalidating a review for
- * it would train authors to re-stamp the hash without re-reading — which
- * costs the field its meaning.
- *
- * Heading TEXT is excluded for the same reason — re-titling a section changes
- * no claim in the prose. But a heading LINE is not: adding or removing a
- * heading changes the document's structure (a new section exists that no one
- * has reviewed), and that must flip the hash even though no non-heading line
- * changed. So each heading line is reduced to its `#` marker (which carries
- * its level and position) rather than dropped outright — retitling a section
- * leaves the marker alone, but appending or removing a heading changes the
- * sequence of markers and therefore the hash. (Swapping two headings of the
- * same level produces the same marker sequence and is not detected — a
- * narrower version of the blind spot this fix closes.)
- */
-export declare function hashReviewedBody(content: string): string;
-export type ProvenanceNote = {
-    kind: 'unreviewed' | 'stale' | 'reviewed';
-    text: string;
-};
-/**
- * The one-line provenance annotation for `lat section` and `lat search`, or
- * null when the document says nothing about its provenance.
- *
- * A document with no `status` produces nothing at all. Most documents in most
- * repositories have no status, and a line on every one of them would be noise
- * that readers learn to skip — which would cost the warning its force on the
- * documents that do carry one.
- */
-export declare function provenanceNote(content: string): ProvenanceNote | null;
-/** Colourize a note for terminal output. */
-export declare function formatProvenanceNote(note: ProvenanceNote, s: Styler): string;
-/**
- * Report documents whose recorded review no longer describes their text.
- *
- * This is a static validation. It needs no history and no database, and it
- * catches most of what a temporal graph would answer.
- */
-export declare function checkStatus(latticeDir: string, projectRoot?: string): Promise<CheckError[]>;

package/dist/src/cli/check-status.js

@@ -1,217 +0,0 @@
-import { createHash } from 'node:crypto';
-import { readFile } from 'node:fs/promises';
-import { dirname, relative } from 'node:path';
-import { listLatticeFiles, parseFrontmatter } from '../lattice.js';
-import { toPosix } from '../walk.js';
-import { quoteUntrusted } from '../untrusted.js';
-import { fencedLineMask } from './gen-index.js';
-/**
- * Who wrote a document, and whether a person has checked it.
- *
- * lat.md states that agents write the graph. Without this field an unmarked
- * claim written by an agent reaches the model carrying exactly the authority
- * of one a person read and approved.
- */
-export const DOC_STATUSES = ['human-reviewed', 'agent-extracted'];
-/**
- * The shortest `reviewed-hash` prefix that is accepted as a match. A full
- * SHA-256 is 64 hex characters and unpleasant to keep in frontmatter, so an
- * author may record an abbreviated form. Eight characters is 32 bits — far
- * past accidental collision for the handful of revisions one document sees,
- * and this value is a staleness signal, not a security boundary.
- */
-const MIN_HASH_PREFIX = 8;
-const HEX = /^[0-9a-f]+$/i;
-/**
- * Read the provenance fields out of a document's frontmatter.
- *
- * Fields live under the top-level `lat:` mapping, so they are read off
- * `LatFrontmatter.raw` rather than being promoted to named fields. Adding a
- * named field would mean editing `parseFrontmatter`, and keeping that function
- * closed to per-feature edits is the whole reason `raw` exists.
- */
-export function readProvenance(content) {
-    const raw = parseFrontmatter(content).raw;
-    const result = {};
-    const status = raw['status'];
-    if (typeof status === 'string')
-        result.status = status;
-    const hash = raw['reviewed-hash'];
-    if (typeof hash === 'string')
-        result.reviewedHash = hash;
-    else if (typeof hash === 'number')
-        result.reviewedHash = String(hash);
-    return result;
-}
-/**
- * Hash the prose a review actually covered.
- *
- * A plain `status` field becomes a lie the moment an agent edits the document:
- * the field still says a person checked the text, but the text is no longer
- * the text that person read. Capturing the content at review time turns that
- * silent failure into a check.
- *
- * Frontmatter is excluded deliberately: adding an unrelated frontmatter key
- * does not change a single claim in the prose, and invalidating a review for
- * it would train authors to re-stamp the hash without re-reading — which
- * costs the field its meaning.
- *
- * Heading TEXT is excluded for the same reason — re-titling a section changes
- * no claim in the prose. But a heading LINE is not: adding or removing a
- * heading changes the document's structure (a new section exists that no one
- * has reviewed), and that must flip the hash even though no non-heading line
- * changed. So each heading line is reduced to its `#` marker (which carries
- * its level and position) rather than dropped outright — retitling a section
- * leaves the marker alone, but appending or removing a heading changes the
- * sequence of markers and therefore the hash. (Swapping two headings of the
- * same level produces the same marker sequence and is not detected — a
- * narrower version of the blind spot this fix closes.)
- */
-export function hashReviewedBody(content) {
-    // Normalize line endings BEFORE stripping frontmatter: the delimiter regex
-    // is written with bare \n, so on a CRLF-saved document it would not match
-    // and the whole frontmatter block — reviewed-hash included — would be
-    // hashed as body, making every such review spuriously stale.
-    const normalized = content.replace(/\r\n/g, '\n');
-    const withoutFrontmatter = normalized.replace(/^---\n[\s\S]*?\n---\n?/, '');
-    const lines = withoutFrontmatter.split('\n');
-    // A `#`-prefixed line inside a fenced code block is a shell comment, not a
-    // heading. Collapsing it would hand an editor a free, unhashed rewrite slot
-    // in every fenced example. The same mask the index reader and writer share.
-    const fenced = fencedLineMask(lines);
-    const body = lines
-        .map((line, i) => {
-        if (fenced[i])
-            return line;
-        const heading = /^(#{1,6})\s/.exec(line);
-        return heading ? heading[1] : line;
-    })
-        // Trailing whitespace is invisible in a diff and must not flip a review.
-        .map((line) => line.replace(/[ \t]+$/, ''))
-        .join('\n')
-        .trim();
-    return createHash('sha256').update(body, 'utf-8').digest('hex');
-}
-function hashMatches(recorded, actual) {
-    const want = recorded.trim().toLowerCase();
-    if (want.length < MIN_HASH_PREFIX || !HEX.test(want))
-        return false;
-    return actual.startsWith(want);
-}
-/**
- * The one-line provenance annotation for `lat section` and `lat search`, or
- * null when the document says nothing about its provenance.
- *
- * A document with no `status` produces nothing at all. Most documents in most
- * repositories have no status, and a line on every one of them would be noise
- * that readers learn to skip — which would cost the warning its force on the
- * documents that do carry one.
- */
-export function provenanceNote(content) {
-    const { status, reviewedHash } = readProvenance(content);
-    if (status === undefined)
-        return null;
-    if (status === 'agent-extracted') {
-        return {
-            kind: 'unreviewed',
-            text: '[unreviewed -- written by an agent, not checked by a person]',
-        };
-    }
-    if (status === 'human-reviewed') {
-        // No hash means an older tree that predates the field. Saying nothing is
-        // deliberate: an upgrade must not repaint an existing graph with warnings.
-        if (reviewedHash === undefined) {
-            return { kind: 'reviewed', text: '[human-reviewed]' };
-        }
-        if (hashMatches(reviewedHash, hashReviewedBody(content))) {
-            return { kind: 'reviewed', text: '[human-reviewed]' };
-        }
-        return {
-            kind: 'stale',
-            text: '[stale review -- the text changed after a person checked it]',
-        };
-    }
-    // An unknown value is repository text and is quoted as such. `lat check
-    // status` reports it; the reader is told only that it means nothing here.
-    return {
-        kind: 'unreviewed',
-        text: `[unrecognized status ${quoteUntrusted(status, 40)} -- treat as unreviewed]`,
-    };
-}
-/** Colourize a note for terminal output. */
-export function formatProvenanceNote(note, s) {
-    if (note.kind === 'reviewed')
-        return s.green(note.text);
-    return s.yellow(note.text);
-}
-/**
- * Report documents whose recorded review no longer describes their text.
- *
- * This is a static validation. It needs no history and no database, and it
- * catches most of what a temporal graph would answer.
- */
-export async function checkStatus(latticeDir, projectRoot = dirname(latticeDir)) {
-    const files = await listLatticeFiles(latticeDir);
-    const errors = [];
-    for (const file of files) {
-        const content = await readFile(file, 'utf-8');
-        const relPath = relative(process.cwd(), file);
-        const target = toPosix(relative(projectRoot, file)).replace(/\.md$/, '');
-        const { status, reviewedHash } = readProvenance(content);
-        if (status === undefined) {
-            if (reviewedHash !== undefined) {
-                errors.push({
-                    file: relPath,
-                    line: 1,
-                    target,
-                    message: `document records a reviewed-hash but no status — add "status: human-reviewed", or drop the hash`,
-                });
-            }
-            continue;
-        }
-        if (!DOC_STATUSES.includes(status)) {
-            errors.push({
-                file: relPath,
-                line: 1,
-                target,
-                message: `document declares unknown status ${quoteUntrusted(status, 40)} — use one of: human-reviewed, agent-extracted`,
-            });
-            continue;
-        }
-        if (status === 'agent-extracted') {
-            if (reviewedHash !== undefined) {
-                errors.push({
-                    file: relPath,
-                    line: 1,
-                    target,
-                    message: `document is agent-extracted but records a reviewed-hash — a hash records that a person checked the text, so set "status: human-reviewed" or drop the hash`,
-                });
-            }
-            continue;
-        }
-        // human-reviewed. No hash is not an error: existing trees must not turn
-        // red on upgrade. It simply buys no staleness detection.
-        if (reviewedHash === undefined)
-            continue;
-        const actual = hashReviewedBody(content);
-        const recorded = reviewedHash.trim().toLowerCase();
-        if (!HEX.test(recorded) || recorded.length < MIN_HASH_PREFIX) {
-            errors.push({
-                file: relPath,
-                line: 1,
-                target,
-                message: `reviewed-hash must be at least ${MIN_HASH_PREFIX} hex characters — record "reviewed-hash: ${actual}"`,
-            });
-            continue;
-        }
-        if (!actual.startsWith(recorded)) {
-            errors.push({
-                file: relPath,
-                line: 1,
-                target,
-                message: `stale review — the text changed after it was reviewed. Re-read it, then record "reviewed-hash: ${actual}"`,
-            });
-        }
-    }
-    return errors;
-}