@plebeiantech/lat.md 0.12.3-fork.6 → 0.12.3-fork.7

package/dist/src/cli/fork-scaffold.d.ts

@@ -1,5 +1,19 @@
-/** Prepend the `require-mode` flag to a root index that has no frontmatter. */
+/**
+ * Turn the gate on in a root index, whatever frontmatter it already has.
+ *
+ * Bailing on any existing frontmatter — the first version of this — produced a
+ * silent no-op: a root index carrying `lat: tags: [...]` could never opt in,
+ * and `lat init` re-offered on every run because the flag it had just written
+ * was not there. Merging is what makes the offer terminate.
+ *
+ * Edited line by line rather than parsed and re-emitted, because re-emitting
+ * reformats the whole block and discards its comments. The one shape that
+ * cannot be edited safely — `lat:` carrying a flow mapping on its own line —
+ * is returned unchanged, and the caller falls back to printing the edit.
+ */
 export declare function stampRequireMode(content: string): string;
+/** Whether the gate is on, read straight from a root index's frontmatter. */
+export declare function requireModeSet(content: string): boolean;
 /**
  * Append the four mode directories to the root index.
  *
@@ -14,3 +28,17 @@ export declare function listModeDirs(content: string): string;
  * underneath its owner.
  */
 export declare function writeForkScaffold(latDir: string): void;
+/**
+ * Offer the gate to a tree `lat init` did not create.
+ *
+ * `writeForkScaffold` runs only on the branch that creates `lat.md/`, which
+ * left the flag unreachable for every project that already had one — that is,
+ * for every project that needs it. Restructuring someone's tree without asking
+ * is still wrong, so this asks.
+ *
+ * Silent when the flag is already set, when a previous run was told no, and
+ * when there is no TTY to ask — the non-interactive path prints the count and
+ * the manual edit instead, and records nothing, so a later interactive run
+ * still offers.
+ */
+export declare function offerRequireMode(latDir: string, interactive: boolean, ask: (message: string) => Promise<boolean>): Promise<void>;

package/dist/src/cli/fork-scaffold.js

@@ -1,5 +1,6 @@
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
-import { basename, join } from 'node:path';
+import { listLatticeFiles, parseFrontmatter } from '../lattice.js';
+import { basename, join, relative, sep } from 'node:path';
 import { styleText } from 'node:util';
 import { DIATAXIS_MODES, MODE_DIRS, indexNameFor } from './check-mode.js';
 /**
@@ -70,11 +71,57 @@ function indexBody(dir) {
         'from a decision belong in `how-to/`, and the facts it fixes belong in ' +
         '`reference/`.\n');
 }
-/** Prepend the `require-mode` flag to a root index that has no frontmatter. */
+/**
+ * Turn the gate on in a root index, whatever frontmatter it already has.
+ *
+ * Bailing on any existing frontmatter — the first version of this — produced a
+ * silent no-op: a root index carrying `lat: tags: [...]` could never opt in,
+ * and `lat init` re-offered on every run because the flag it had just written
+ * was not there. Merging is what makes the offer terminate.
+ *
+ * Edited line by line rather than parsed and re-emitted, because re-emitting
+ * reformats the whole block and discards its comments. The one shape that
+ * cannot be edited safely — `lat:` carrying a flow mapping on its own line —
+ * is returned unchanged, and the caller falls back to printing the edit.
+ */
 export function stampRequireMode(content) {
-    if (/^---\n/.test(content))
+    const fence = content.match(/^---\n([\s\S]*?)\n---[ \t]*(\r?\n|$)/);
+    if (!fence) {
+        return `---\nlat:\n  require-mode: true\n---\n\n${content.replace(/^\n+/, '')}`;
+    }
+    const body = fence[1];
+    if (/^\s*require-mode\s*:/m.test(body))
         return content;
-    return `---\nlat:\n  require-mode: true\n---\n\n${content.replace(/^\n+/, '')}`;
+    const lines = body.split('\n');
+    const latAt = lines.findIndex((line) => /^lat\s*:/.test(line));
+    let merged;
+    if (latAt === -1) {
+        merged = [...lines, 'lat:', '  require-mode: true'];
+    }
+    else if (lines[latAt].replace(/^lat\s*:/, '').trim() !== '') {
+        // `lat: {mode: reference}` or `lat: &anchor` — a line-based insert would
+        // corrupt it, so say nothing and let the caller print the edit.
+        return content;
+    }
+    else {
+        // Siblings must share indentation, so take it from the existing first
+        // child rather than assuming two spaces.
+        const child = lines
+            .slice(latAt + 1)
+            .find((line) => line.trim() !== '' && /^\s/.test(line));
+        const indent = child ? (child.match(/^\s+/)?.[0] ?? '  ') : '  ';
+        merged = [
+            ...lines.slice(0, latAt + 1),
+            `${indent}require-mode: true`,
+            ...lines.slice(latAt + 1),
+        ];
+    }
+    const end = fence[0].length;
+    return `---\n${merged.join('\n')}\n---${fence[2] || '\n'}${content.slice(end)}`;
+}
+/** Whether the gate is on, read straight from a root index's frontmatter. */
+export function requireModeSet(content) {
+    return parseFrontmatter(content).raw['require-mode'] !== undefined;
 }
 /**
  * Append the four mode directories to the root index.
@@ -127,3 +174,127 @@ export function writeForkScaffold(latDir) {
             styleText('dim', ' (every document belongs in one of these)'));
     }
 }
+// ── Adopting the gate in a tree that already exists ──────────────────
+/**
+ * Where a declined offer is remembered.
+ *
+ * Fork-owned rather than a field on upstream's `lat_init.json`, so recording
+ * it costs no edit to `src/init-version.ts`. `lat.md/.cache/` is already in
+ * the scaffolded `.gitignore`, so the marker stays out of the repository.
+ */
+function declinePath(latDir) {
+    return join(latDir, '.cache', 'lat_fork.json');
+}
+function declined(latDir) {
+    try {
+        const raw = JSON.parse(readFileSync(declinePath(latDir), 'utf-8'));
+        return (typeof raw === 'object' &&
+            raw !== null &&
+            raw['require_mode_declined'] === true);
+    }
+    catch {
+        return false;
+    }
+}
+function recordDecline(latDir) {
+    mkdirSync(join(latDir, '.cache'), { recursive: true });
+    writeFileSync(declinePath(latDir), JSON.stringify({ require_mode_declined: true }, null, 2) + '\n');
+}
+/** Documents the gate would reject today: not an index, no mode either way. */
+async function unmodedDocuments(latDir) {
+    const modeDirs = new Set(DIATAXIS_MODES.map((mode) => MODE_DIRS[mode]));
+    const files = await listLatticeFiles(latDir);
+    const offenders = [];
+    for (const file of files) {
+        const rel = relative(latDir, file).split(sep).join('/');
+        const segments = rel.split('/');
+        const fileName = segments.pop();
+        const holder = segments.length === 0 ? basename(latDir) : segments.at(-1);
+        if (fileName === indexNameFor(holder))
+            continue;
+        if (segments.length > 0 && modeDirs.has(segments[0]))
+            continue;
+        const declaredMode = parseFrontmatter(readFileSync(file, 'utf-8')).raw['mode'];
+        if (typeof declaredMode === 'string')
+            continue;
+        offenders.push(rel);
+    }
+    return offenders;
+}
+/**
+ * Offer the gate to a tree `lat init` did not create.
+ *
+ * `writeForkScaffold` runs only on the branch that creates `lat.md/`, which
+ * left the flag unreachable for every project that already had one — that is,
+ * for every project that needs it. Restructuring someone's tree without asking
+ * is still wrong, so this asks.
+ *
+ * Silent when the flag is already set, when a previous run was told no, and
+ * when there is no TTY to ask — the non-interactive path prints the count and
+ * the manual edit instead, and records nothing, so a later interactive run
+ * still offers.
+ */
+export async function offerRequireMode(latDir, interactive, ask) {
+    const rootIndex = join(latDir, indexNameFor(basename(latDir)));
+    if (!existsSync(rootIndex))
+        return;
+    if (requireModeSet(readFileSync(rootIndex, 'utf-8')))
+        return;
+    if (declined(latDir))
+        return;
+    const offenders = await unmodedDocuments(latDir);
+    console.log('');
+    console.log(styleText('bold', 'Diátaxis modes'));
+    console.log('  ' +
+        styleText('dim', 'Every document belongs in one of four modes. Without') +
+        ' require-mode ' +
+        styleText('dim', 'a document'));
+    console.log('  ' +
+        styleText('dim', 'placed outside a mode directory is checked against no shape rule at all.'));
+    if (offenders.length > 0) {
+        console.log('');
+        console.log(`  ${styleText('yellow', String(offenders.length))} document(s) would need a mode:`);
+        for (const name of offenders.slice(0, 5)) {
+            console.log('    ' + styleText('dim', name));
+        }
+        if (offenders.length > 5) {
+            console.log('    ' + styleText('dim', `... and ${offenders.length - 5} more`));
+        }
+    }
+    if (!interactive) {
+        console.log('');
+        console.log('  ' +
+            styleText('dim', 'To turn it on, add this to the top of') +
+            ` ${basename(latDir)}/${indexNameFor(basename(latDir))}:`);
+        console.log('');
+        for (const line of ['---', 'lat:', '  require-mode: true', '---']) {
+            console.log('    ' + styleText('cyan', line));
+        }
+        return;
+    }
+    console.log('');
+    if (!(await ask('  Turn require-mode on for this project?'))) {
+        recordDecline(latDir);
+        console.log('  ' +
+            styleText('dim', 'Skipped. Add') +
+            ' require-mode: true ' +
+            styleText('dim', 'to the root index whenever you want it.'));
+        return;
+    }
+    writeForkScaffold(latDir);
+    // The one frontmatter shape `stampRequireMode` refuses to edit. Saying so
+    // beats re-offering forever on a flag that never lands.
+    if (!requireModeSet(readFileSync(rootIndex, 'utf-8'))) {
+        console.log('  ' +
+            styleText('yellow', 'Could not edit the frontmatter safely.') +
+            styleText('dim', ' Add this under its `lat:` mapping by hand:'));
+        console.log('    ' + styleText('cyan', 'require-mode: true'));
+        return;
+    }
+    if (offenders.length > 0) {
+        console.log('  ' +
+            styleText('dim', 'Run') +
+            ' lat check ' +
+            styleText('dim', 'to see which documents need placing.'));
+    }
+}

package/dist/src/cli/init.js

@@ -16,7 +16,7 @@ import { getLocalVersion, fetchLatestVersion } from '../version.js';
 import { selectMenu } from './select-menu.js';
 import { checklistMenu } from './checklist-menu.js';
 import { writeForkInstructions } from './fork-instructions.js';
-import { writeForkScaffold } from './fork-scaffold.js';
+import { offerRequireMode, writeForkScaffold } from './fork-scaffold.js';
 async function confirm(rl, message) {
     while (true) {
         let answer;
@@ -957,6 +957,7 @@ export async function initCmd(targetDir) {
                 output: process.stdout,
             });
         }
+        await offerRequireMode(latDir, interactive, ask);
         if (!anySelected) {
             // Embedding setup is complete even when the user does not configure an
             // agent. Stamp the version so future non-interactive runs do not reapply

package/dist/src/init-version.d.ts

@@ -3,7 +3,7 @@
  * requires users to re-run it (e.g. new hooks, generated files, MCP config, or
  * a configuration migration).
  */
-export declare const INIT_VERSION = 6;
+export declare const INIT_VERSION = 7;
 export declare function readInitVersion(latDir: string): number | null;
 export declare function readFileHash(latDir: string, relPath: string): string | null;
 export declare function contentHash(content: string): string;

package/dist/src/init-version.js

@@ -6,7 +6,7 @@ import { join } from 'node:path';
  * requires users to re-run it (e.g. new hooks, generated files, MCP config, or
  * a configuration migration).
  */
-export const INIT_VERSION = 6;
+export const INIT_VERSION = 7;
 function cachePath(latDir) {
     return join(latDir, '.cache', 'lat_init.json');
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@plebeiantech/lat.md",
-  "version": "0.12.3-fork.6",
+  "version": "0.12.3-fork.7",
   "description": "A knowledge graph for your codebase, written in markdown",
   "type": "module",
   "license": "MIT",