@plebeiantech/lat.md 0.12.3-fork.1 → 0.12.3-fork.10

package/README.md

@@ -3,10 +3,12 @@
 </p>
 
 <p align="center">
-  <a href="https://github.com/1st1/lat.md/actions/workflows/ci.yml"><img src="https://github.com/1st1/lat.md/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
-  <a href="https://www.npmjs.com/package/lat.md"><img src="https://img.shields.io/npm/v/lat.md" alt="npm"></a>
+  <a href="https://github.com/PlebeianTech/lat.md/actions/workflows/ci.yml"><img src="https://github.com/PlebeianTech/lat.md/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
+  <a href="https://www.npmjs.com/package/@plebeiantech/lat.md"><img src="https://img.shields.io/npm/v/@plebeiantech/lat.md" alt="npm"></a>
 </p>
 
+# Fork of https://github.com/vercel-labs/lat.md
+
 <p align="center">A knowledge graph for your codebase, written in markdown.</p>
 
 ## The problem
@@ -35,12 +37,46 @@ The `lat` CLI gives agents and humans a system to navigate and maintain the grap
 
 ## Install
 
+This is a fork. It publishes as [`@plebeiantech/lat.md`](https://www.npmjs.com/package/@plebeiantech/lat.md) and never under upstream's `lat.md` name, so the two can coexist.
+
+With [mise](https://mise.jdx.dev/):
+
+```bash
+mise settings add minimum_release_age_excludes npm:@plebeiantech/lat.md
+mise use -g npm:@plebeiantech/lat.md@latest
+```
+
+The first line is needed once per machine. mise quarantines any npm version published in the last day or so, and a fresh release is invisible until that window passes — the exclude waives it for this package alone and leaves the guard in force for every other tool.
+
+With npm:
+
+```bash
+npm install -g @plebeiantech/lat.md
+```
+
+Or straight from a GitHub Release, which needs no registry and no authentication:
+
 ```bash
-npm install -g lat.md
+npm i -g --prefix ~/.local/lat https://github.com/PlebeianTech/lat.md/releases/latest/download/lat.md-latest.tgz
 ```
 
+That last one wants `~/.local/lat/bin` on your `PATH`. A fixed prefix keeps the install independent of whichever Node version is active.
+
+Pick one route and stay on it. A Release-route install left on `PATH` shadows a mise-managed one — `mise upgrade` then reports a new version while the shell keeps running the old binary.
+
 Then run `lat init` in the repo you want to use lat in.
 
+### As a Claude Code plugin
+
+The hooks are also packaged as a plugin, installable straight from this repository:
+
+```
+/plugin marketplace add PlebeianTech/lat.md
+/plugin install lat-md@lat-md
+```
+
+The plugin ships hooks only and finds `lat` on your `PATH`, accepting a build only if its version carries a `-fork` suffix.
+
 ## How it works
 
 Run `lat init` to scaffold a `lat.md/` directory, then write markdown files describing your architecture, business logic, test specs — whatever matters. Link between sections using `[[file#Section#Subsection]]` syntax. Link to source code symbols with `[[src/auth.ts#validateToken]]`. Annotate source code with `// @lat: [[section-id]]` (or `# @lat: [[section-id]]` in Python) comments to tie implementation back to concepts.

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

@@ -0,0 +1,2 @@
+import type { CheckError } from './check.js';
+export declare function checkCoverage(latticeDir: string, projectRoot?: string): Promise<CheckError[]>;

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

@@ -0,0 +1,71 @@
+import { readFile } from 'node:fs/promises';
+import { relative } from 'node:path';
+import { scanCodeRefs } from '../code-refs.js';
+import { listLatticeFiles } from '../lattice.js';
+import { indexNameFor } from './check-mode.js';
+import { toPosix } from '../walk.js';
+import { basename, dirname } from 'node:path';
+/**
+ * Fail a `lat.md/` tree that has documents and no `@lat:` ref pointing into it
+ * from anywhere in the codebase.
+ *
+ * `require-code-mention` was the only thing asking for refs, and it is opt-in
+ * frontmatter: an agent setting up a tree can simply not write it, and every
+ * check still passes. One did. Its reasons were both ordinary — it read a list
+ * of example comment markers as an exclusive language list and concluded its
+ * language was unsupported, and it was optimising for a green check rather
+ * than a correct one, so the option that could not fail was the one it took.
+ *
+ * A graph nothing points at cannot be reached from the code, which is the only
+ * reason it exists. So the floor is one ref, and the message says where to put
+ * the first one.
+ *
+ * Deliberately a floor and not a coverage ratio. Half this repository's own
+ * documents have no incoming ref and should not have one — a per-document rule
+ * would have to be either wrong here or watered down everywhere.
+ */
+/** Nothing to anchor: a tree of pure navigation, or a project with no code. */
+function isIndex(latticeDir, file) {
+    const holder = basename(dirname(file));
+    return (basename(file) ===
+        indexNameFor(holder === '' ? basename(latticeDir) : holder));
+}
+export async function checkCoverage(latticeDir, projectRoot = dirname(latticeDir)) {
+    const files = await listLatticeFiles(latticeDir);
+    const documents = files.filter((f) => !isIndex(latticeDir, f));
+    if (documents.length === 0)
+        return [];
+    const scan = await scanCodeRefs(projectRoot);
+    if (scan.files.length === 0)
+        return [];
+    if (scan.refs.length > 0)
+        return [];
+    const rootIndexPath = `${latticeDir}/${indexNameFor(basename(latticeDir))}`;
+    const rootIndexRel = toPosix(relative(process.cwd(), rootIndexPath));
+    // Quote the ref the reader should actually paste. A generic placeholder gets
+    // pasted verbatim and then fails `lat check code-refs`, which turns one
+    // error into two.
+    const stem = basename(latticeDir).replace(/\.md$/, '');
+    let anchor = `${stem}#Your Project`;
+    try {
+        const heading = (await readFile(rootIndexPath, 'utf-8')).match(/^#\s+(.+)$/m);
+        if (heading)
+            anchor = `${stem}#${heading[1].trim()}`;
+    }
+    catch {
+        // No root index, or unreadable — the placeholder still names the shape.
+    }
+    return [
+        {
+            file: rootIndexRel,
+            line: 1,
+            target: toPosix(relative(projectRoot, latticeDir)),
+            message: `${documents.length} document(s) here and no \`@lat:\` code ref anywhere in the project — nothing in the codebase can reach this graph.\n` +
+                '    Start at the application entrypoint (config/application.rb, src/index.ts, main.go, manage.py) and point it at the root index:\n' +
+                `        # @lat: [[${anchor}]]\n` +
+                '    Then add one ref per section that source code implements, at that code.\n' +
+                '    The marker is a comment syntax, not a language allowlist: `//` for C-family, `#` for Ruby, Python, shell, Elixir and the rest. The scan is textual and reads every non-markdown file.\n' +
+                '    An `@lat:` line is a machine directive, like a magic comment or a linter pragma. A project convention that minimises comments does not reach it.',
+        },
+    ];
+}

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

@@ -3,4 +3,19 @@ export declare const DIATAXIS_MODES: readonly ["tutorial", "how-to", "reference"
 export type DiataxisMode = (typeof DIATAXIS_MODES)[number];
 /** Directory below lat.md/ that holds each mode. */
 export declare const MODE_DIRS: Record<DiataxisMode, string>;
-export declare function checkMode(latticeDir: string, projectRoot?: string): Promise<CheckError[]>;
+/**
+ * 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 declare function indexNameFor(dirName: string): string;
+export type CheckModeOptions = {
+    /**
+     * Enforce as if the root index said this, whatever it actually says. Used to
+     * price adoption — running once each way and taking the difference is what
+     * the offer in `lat init` reports, and it keeps that number defined by this
+     * checker rather than by a second copy of its rules.
+     */
+    requireMode?: boolean;
+};
+export declare function checkMode(latticeDir: string, projectRoot?: string, options?: CheckModeOptions): Promise<CheckError[]>;

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

@@ -1,5 +1,5 @@
 import { readFile } from 'node:fs/promises';
-import { dirname, relative } from 'node:path';
+import { basename, dirname, join, relative } from 'node:path';
 import { listLatticeFiles, parseFrontmatter } from '../lattice.js';
 import { parse } from '../parser.js';
 import { quoteUntrusted } from '../untrusted.js';
@@ -18,7 +18,11 @@ export const MODE_DIRS = {
     explanation: 'explanation',
 };
 /** Reverse lookup: first path segment -> mode. Built once, not per file. */
-const DIR_TO_MODE = Object.fromEntries(DIATAXIS_MODES.map((mode) => [MODE_DIRS[mode], mode]));
+// 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.
@@ -177,9 +181,53 @@ function findImperativeHits(tree, content) {
     }
     return hits;
 }
-export async function checkMode(latticeDir, projectRoot = dirname(latticeDir)) {
+/**
+ * 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);
@@ -234,8 +282,21 @@ export async function checkMode(latticeDir, projectRoot = dirname(latticeDir)) {
             continue;
         }
         const mode = (declared ?? dirMode);
-        if (mode === undefined)
+        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)) {

package/dist/src/cli/check.js

@@ -6,6 +6,7 @@ import { scanCodeRefs } from '../code-refs.js';
 import { checkMode } from './check-mode.js';
 import { checkStatus } from './check-status.js';
 import { checkFrontmatter } from './check-frontmatter.js';
+import { checkCoverage } from './check-coverage.js';
 import { indexEntryNameFromDest } from './link-scheme.js';
 import { fencedLineMask } from './gen-index.js';
 import { SOURCE_EXTENSIONS, clearSymbolCache } from '../source-parser.js';
@@ -621,6 +622,7 @@ export async function checkAllCommand(ctx, opts = {}) {
     const modeErrors = await checkMode(ctx.latDir, ctx.projectRoot);
     const statusErrors = await checkStatus(ctx.latDir, ctx.projectRoot);
     const fmErrors = await checkFrontmatter(ctx.latDir, ctx.projectRoot);
+    const coverageErrors = await checkCoverage(ctx.latDir, ctx.projectRoot);
     const elapsed = Date.now() - startTime;
     const allErrors = [...md.errors, ...linkErrors, ...code.errors];
     const allFiles = { ...md.files };
@@ -658,12 +660,14 @@ export async function checkAllCommand(ctx, opts = {}) {
     lines.push(...formatCheckErrors(modeErrors, s));
     lines.push(...formatCheckErrors(statusErrors, s));
     lines.push(...formatCheckErrors(fmErrors, s));
+    lines.push(...formatCheckErrors(coverageErrors, s));
     const totalErrors = allErrors.length +
         indexErrors.length +
         sectionErrors.length +
         modeErrors.length +
         statusErrors.length +
-        fmErrors.length;
+        fmErrors.length +
+        coverageErrors.length;
     if (totalErrors > 0) {
         lines.push(formatErrorCount(totalErrors, s));
         return { output: lines.join('\n'), isError: true };

package/dist/src/cli/comment-guard.d.ts

@@ -1,4 +1,18 @@
 import { type ToolInput } from './comment-reminder.js';
+/**
+ * The blocking half of the comment convention. `computeCommentReminder` runs
+ * at PostToolUse and only advises: by then the prose is already on disk, and
+ * it is deduped to once per file per session, so the second rationale block
+ * in a file draws no signal at all.
+ *
+ * This runs at PreToolUse instead, where `tool_input` is visible before the
+ * edit is applied and the hook can answer `deny`. A multi-line comment is
+ * refused outright and the agent is told to put the reasoning in `lat.md/`
+ * and leave a `@lat:` pointer behind.
+ *
+ * There is deliberately no per-session dedup here. A gate that fires once is
+ * not a gate.
+ */
 export type PreToolUseInput = {
     hook_event_name?: string;
     session_id?: string;

package/dist/src/cli/comment-guard.js

@@ -1,28 +1,4 @@
-import { candidateCommentLines, extractWrittenText, hasLatTree, matchFamily, resolveProjectRoot, } from './comment-reminder.js';
-/**
- * The blocking half of the comment convention. `computeCommentReminder` runs
- * at PostToolUse and only advises: by then the prose is already on disk, and
- * it is deduped to once per file per session, so the second rationale block
- * in a file draws no signal at all.
- *
- * This runs at PreToolUse instead, where `tool_input` is visible before the
- * edit is applied and the hook can answer `deny`. A multi-line comment is
- * refused outright and the agent is told to put the reasoning in `lat.md/`
- * and leave a `@lat:` pointer behind.
- *
- * There is deliberately no per-session dedup here. A gate that fires once is
- * not a gate.
- */
-/** Minimum candidate comment lines in one write before the edit is refused.
- *  A single line ("// bytes, not chars") is the bare-fact case the convention
- *  explicitly allows; two or more is a block of prose. */
-const BLOCK_THRESHOLD = 2;
-/** Explicit, reviewable opt-out. Spelled the same as the `lat:ignore` token
- *  [[src/code-refs.ts]] already honours, so a project has one escape hatch to
- *  learn rather than two. It suppresses only the line it appears on, which
- *  keeps a deliberate exception visible in the diff instead of silently
- *  disarming the gate for a whole file. */
-const LAT_IGNORE_RE = /(?<![\w])lat:ignore(?![-\w])/;
+import { hasLatTree, judgeWrittenComments, matchFamily, resolveProjectRoot, } from './comment-reminder.js';
 function buildReason(opts) {
     const where = opts.hasTree
         ? '  1. Put the reasoning in a lat.md/ section. Verbatim is fine — it does\n' +
@@ -43,8 +19,12 @@ function buildReason(opts) {
         '  3. Re-apply the edit with the prose replaced by that one pointer line.\n\n' +
         'If a comment only narrates what the code does, delete it rather than ' +
         'moving it — a reader could reconstruct it from the code.\n\n' +
-        `To keep a specific line anyway, put \`lat:ignore\` on it. That is an ` +
-        'explicit, reviewable exception, not a way to silence the gate.');
+        'Two exits, if neither applies:\n' +
+        '  - Put `lat:ignore` on a specific line to keep it. An explicit, ' +
+        'reviewable exception, not a way to silence the gate.\n' +
+        '  - Use `Edit` rather than a whole-file `Write`. Re-emitting a comment ' +
+        'the file already holds is free in either shape, but an `Edit` puts far ' +
+        'less text in front of the count.');
 }
 /**
  * Returns the denial reason for a single Edit/Write/MultiEdit call, or `null`
@@ -93,18 +73,15 @@ export function computeCommentBlock(input) {
     const family = matchFamily(filePath);
     if (!family)
         return null;
-    const written = extractWrittenText(toolInput);
-    if (!written)
-        return null;
-    const candidates = candidateCommentLines(written, family).filter((line) => !LAT_IGNORE_RE.test(line));
-    if (candidates.length < BLOCK_THRESHOLD)
+    const verdict = judgeWrittenComments(toolInput, family, 'before-write');
+    if (!verdict.flagged)
         return null;
     const projectRoot = resolveProjectRoot(filePath, input.cwd);
     if (!projectRoot)
         return null;
     return buildReason({
         base: filePath.split('/').pop() ?? filePath,
-        count: candidates.length,
+        count: verdict.count,
         marker: family.marker,
         hasTree: hasLatTree(projectRoot),
     });

package/dist/src/cli/comment-reminder.d.ts

@@ -27,20 +27,79 @@ export declare function matchFamily(filePath: string): CommentFamily | null;
 export type ToolInput = {
     file_path?: string;
     content?: string;
+    old_string?: string;
     new_string?: string;
     edits?: {
+        old_string?: string;
         new_string?: string;
     }[];
 };
-/** Only the NEW text — reading the file would fire on every pre-existing
- * comment in it, nagging about prose the agent did not write. */
-export declare function extractWrittenText(toolInput: ToolInput): string;
-/** Comment lines worth reminding about. Dropped before counting:
+/**
+ * Which side of the tool call the caller is on.
+ *
+ * `'before-write'` — PreToolUse. The file on disk is still the pre-edit state,
+ * so it is usable as a baseline for a whole-file `Write`, which carries no
+ * other record of what it replaced.
+ *
+ * `'after-write'` — PostToolUse. The write has landed, so the file contains
+ * every line of `content` by construction. Diffing against it there cancels
+ * the whole payload and the caller sees nothing at all.
+ *
+ * An `Edit` carries its own `old_string` and needs neither reading: its
+ * baseline is phase-independent, which is the shape to prefer.
+ *
+ * The parameter is required so a third call site has to answer the question
+ * rather than inherit whichever default happened to suit the first two.
+ */
+export type WritePhase = 'before-write' | 'after-write';
+/** Explicit, reviewable per-line opt-out, spelled the same as the token
+ * [[src/code-refs.ts]] already honours so a project has one escape hatch to
+ * learn rather than two. It lives here, not in the guard, because the
+ * advisory and blocking halves have to agree on it: an exemption that the
+ * gate honours but the reminder does not just relocates the nag.
+ * It suppresses only the line it appears on, keeping a deliberate exception
+ * visible in the diff instead of silently disarming the convention for a
+ * whole file. */
+export declare const LAT_IGNORE_RE: RegExp;
+/** Whether one line is a comment worth counting. Not counted:
  *   - a line that already carries a `@lat:` pointer (the compliant state)
+ *   - a line carrying the explicit opt-out token
  *   - machine directives: shebangs, magic comments, linter/type pragmas
  *   - decoration with no alphanumeric character (`# ----`, `//////`, a bare
- *     `*​/` closing a block) */
-export declare function candidateCommentLines(written: string, family: CommentFamily): string[];
+ *     `*​/` closing a block)
+ *
+ * Both halves of the convention call this and nothing else, so the gate and
+ * the reminder cannot drift apart on what counts as prose. */
+export declare function isCandidateCommentLine(line: string, family: CommentFamily): boolean;
+export type CommentVerdict = {
+    /** Candidate comment lines this call is answerable for. Names the number
+     * printed in the denial or the reminder. */
+    count: number;
+    /** Whether the call warrants a denial from the gate or a reminder from its
+     * advisory half. */
+    flagged: boolean;
+};
+/**
+ * What one Edit/Write/MultiEdit call did to the comments in a file.
+ *
+ * Two rules, because neither alone survives contact with an agent:
+ *
+ * A run of `PROSE_THRESHOLD` or more *adjacent* comment lines is flagged as
+ * soon as any one of them is new. Counting only the new lines lets a block be
+ * grown one line per `Edit` and never reach the threshold — and the denial
+ * text itself recommends `Edit` over `Write`, so the technique is advertised.
+ * What matters is the block the edit leaves behind, not the increment.
+ *
+ * Isolated new comment lines are flagged once `PROSE_THRESHOLD` of them
+ * accumulate anywhere in the call. Two one-line comments in different places
+ * are still two lines of prose; without this a scattered write walks past the
+ * adjacency rule.
+ *
+ * Neither rule counts a line that was already there, so re-emitting a
+ * comment — the whole of a `Write`'s payload, or the lines bracketing an
+ * `Edit` — stays free.
+ */
+export declare function judgeWrittenComments(toolInput: ToolInput, family: CommentFamily, phase: WritePhase): CommentVerdict;
 /** Resolvable project root, required so a scratch file in /tmp is not treated
  * as a project. `cwd` is preferred (matches CLAUDE_PROJECT_DIR / payload cwd
  * conventions); falls back to `git rev-parse --show-toplevel`. */