@plebeiantech/lat.md 0.12.3-fork.12 → 0.12.3-fork.14

package/README.md

@@ -77,6 +77,30 @@ The hooks are also packaged as a plugin, installable straight from this reposito
 
 The plugin ships hooks only and finds `lat` on your `PATH`, accepting a build only if its version carries a `-fork` suffix.
 
+### As an Antigravity / Gemini CLI plugin
+
+The hooks, rules, and skills are packaged as an Antigravity plugin under `plugins/lat-md/`.
+
+You can install it directly without cloning the repository:
+
+**Global installation (all local projects):**
+```bash
+mkdir -p ~/.gemini/config/plugins/lat-md && \
+curl -sL https://github.com/PlebeianTech/lat.md/archive/refs/heads/main.tar.gz | \
+  tar -xz -C ~/.gemini/config/plugins/lat-md --strip-components=2 lat.md-main/plugins/lat-md
+```
+
+**Workspace installation (single repository):**
+```bash
+mkdir -p .agents/plugins/lat-md && \
+curl -sL https://github.com/PlebeianTech/lat.md/archive/refs/heads/main.tar.gz | \
+  tar -xz -C .agents/plugins/lat-md --strip-components=2 lat.md-main/plugins/lat-md
+```
+
+Alternatively, install `@plebeiantech/lat.md` via npm/mise, run `lat init` in your project, and select **Antigravity / Gemini** from the agent checklist.
+
+
+
 ## 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-context.d.ts

@@ -0,0 +1,56 @@
+import { type LatFrontmatter, type MdLink, type Ref, type Section, type SectionSlugIndex } from '../lattice-model.js';
+import { type ScanResult } from '../code-refs.js';
+import { type ResolveSourceSymbolOptions } from '../source-parser.js';
+import { type ExternalResolver, type ResolvedExternalContent } from '../external-sources.js';
+import type { Profiler } from '../profiler.js';
+import { type MarkdownAnalysisExecutor, type MarkdownProjectAnalysis } from '../project-analysis.js';
+import type { LocalMarkdownDiagnostic } from '../markdown-validation.js';
+export type CheckSectionIndex = {
+    sectionIds: Set<string>;
+    fileIndex: Map<string, string[]>;
+    slugIndex: SectionSlugIndex;
+};
+/** Lazy, command-scoped cache shared by every validator in one check run. */
+export declare class CheckRunContext {
+    readonly latticeDir: string;
+    readonly projectRoot: string;
+    readonly profile?: Profiler | undefined;
+    readonly executor: MarkdownAnalysisExecutor;
+    private projectPromise?;
+    private codeRefsPromise?;
+    private externalResolverPromise?;
+    private reconciledExternalPromise?;
+    private sourceSymbolCacheCleared;
+    private readonly sourceParserRuntime;
+    private readonly headingPromises;
+    private readonly externalContentPromises;
+    private readonly repositoryLinkErrorPromises;
+    private readonly auxiliaryFilePromises;
+    constructor(latticeDir: string, projectRoot: string, profile?: Profiler | undefined, executor?: MarkdownAnalysisExecutor);
+    private time;
+    private timeSync;
+    private recordAnalysis;
+    private recordParserImport;
+    private recordSourceAnalysis;
+    private recordExternalDocumentAnalysis;
+    sourceSymbolOptions(): ResolveSourceSymbolOptions;
+    clearSourceSymbolCache(): void;
+    project(): Promise<MarkdownProjectAnalysis>;
+    entries(): Promise<string[]>;
+    markdownFiles(): Promise<string[]>;
+    private file;
+    content(file: string): Promise<string>;
+    sections(file: string): Promise<Section[]>;
+    refs(file: string): Promise<Ref[]>;
+    links(file: string): Promise<MdLink[]>;
+    frontmatter(file: string): Promise<LatFrontmatter>;
+    diagnostics(file: string): Promise<LocalMarkdownDiagnostic[]>;
+    allSections(): Promise<Section[]>;
+    sectionIndex(): Promise<CheckSectionIndex>;
+    headings(file: string): Promise<Set<string>>;
+    codeRefs(): Promise<ScanResult>;
+    private loadExternalResolver;
+    externalResolver(): Promise<ExternalResolver>;
+    resolveExternal(target: string): Promise<ResolvedExternalContent>;
+    resolveRepositoryLink(target: string, resolveLink: () => Promise<string | null>): Promise<string | null>;
+}

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

@@ -0,0 +1,215 @@
+import { flattenSections, } from '../lattice-model.js';
+import { scanCodeRefs } from '../code-refs.js';
+import { SourceParserRuntime, } from '../source-parser.js';
+import { createExternalResolver, } from '../external-sources.js';
+import { analyzeMarkdownProject, } from '../project-analysis.js';
+import { analyzeMarkdownPath } from '../markdown-analysis-cache.js';
+/** Lazy, command-scoped cache shared by every validator in one check run. */
+export class CheckRunContext {
+    latticeDir;
+    projectRoot;
+    profile;
+    executor;
+    projectPromise;
+    codeRefsPromise;
+    externalResolverPromise;
+    reconciledExternalPromise;
+    sourceSymbolCacheCleared = false;
+    sourceParserRuntime = new SourceParserRuntime();
+    headingPromises = new Map();
+    externalContentPromises = new Map();
+    repositoryLinkErrorPromises = new Map();
+    auxiliaryFilePromises = new Map();
+    constructor(latticeDir, projectRoot, profile, executor = 'auto') {
+        this.latticeDir = latticeDir;
+        this.projectRoot = projectRoot;
+        this.profile = profile;
+        this.executor = executor;
+    }
+    time(label, work, detail) {
+        return this.profile ? this.profile.time(label, work, detail) : work();
+    }
+    timeSync(label, work, detail) {
+        return this.profile ? this.profile.timeSync(label, work, detail) : work();
+    }
+    recordAnalysis(analysis) {
+        if (!this.profile)
+            return;
+        const detail = analysis.path;
+        const timings = analysis.timings;
+        this.profile.record('read Markdown file', timings.readMs, detail);
+        this.profile.record('hash Markdown file', timings.hashMs, detail);
+        if (timings.cacheStatus !== 'disabled') {
+            this.profile.record('read parsed Markdown cache', timings.cacheReadMs, detail);
+            this.profile.record(`parsed Markdown cache ${timings.cacheStatus}`, 0);
+        }
+        if (timings.cacheStatus === 'hit')
+            return;
+        this.profile.record('parse Markdown AST', timings.parseMs, detail);
+        this.profile.record('extract Markdown sections', timings.sectionsMs, detail);
+        this.profile.record('extract wiki links', timings.refsMs, detail);
+        this.profile.record('extract relative links', timings.linksMs, detail);
+        this.profile.record('extract Markdown presentation facts', timings.paragraphsMs, detail);
+        this.profile.record('parse code-mention frontmatter', timings.frontmatterMs, detail);
+        this.profile.record('extract directory-index entries', timings.indexEntriesMs, detail);
+        this.profile.record('validate local Markdown facts', timings.diagnosticsMs, detail);
+        if (timings.cacheStatus === 'miss') {
+            this.profile.record('write parsed Markdown cache', timings.cacheWriteMs, detail);
+        }
+    }
+    recordParserImport(event) {
+        if (!this.profile)
+            return;
+        this.profile.record(event.imported ? `import ${event.parser}` : `skip ${event.parser} import`, event.durationMs, event.detail);
+    }
+    recordSourceAnalysis(analysis) {
+        if (!this.profile)
+            return;
+        const detail = analysis.path;
+        const timings = analysis.timings;
+        this.profile.record('read source file', timings.readMs, detail);
+        this.profile.record('hash source file', timings.hashMs, detail);
+        if (timings.cacheStatus !== 'disabled') {
+            this.profile.record('read parsed source cache', timings.cacheReadMs, detail);
+            this.profile.record(`parsed source cache ${timings.cacheStatus}`, 0);
+        }
+        if (timings.cacheStatus === 'hit')
+            return;
+        this.profile.record('parse source symbols', timings.parseMs, detail);
+        if (timings.cacheStatus === 'miss') {
+            this.profile.record('write parsed source cache', timings.cacheWriteMs, detail);
+        }
+    }
+    recordExternalDocumentAnalysis(analysis) {
+        if (!this.profile)
+            return;
+        const detail = analysis.path;
+        const timings = analysis.timings;
+        this.profile.record('hash external document', timings.hashMs, detail);
+        if (timings.cacheStatus !== 'disabled') {
+            this.profile.record('read parsed external document cache', timings.cacheReadMs, detail);
+            this.profile.record(`parsed external document cache ${timings.cacheStatus}`, 0);
+        }
+        if (timings.cacheStatus === 'hit')
+            return;
+        this.profile.record('parse external document', timings.parseMs, detail);
+        if (timings.cacheStatus === 'miss') {
+            this.profile.record('write parsed external document cache', timings.cacheWriteMs, detail);
+        }
+    }
+    sourceSymbolOptions() {
+        return {
+            latDir: this.latticeDir,
+            runtime: this.sourceParserRuntime,
+            onFileAnalyzed: (analysis) => this.recordSourceAnalysis(analysis),
+        };
+    }
+    clearSourceSymbolCache() {
+        if (this.sourceSymbolCacheCleared)
+            return;
+        this.sourceSymbolCacheCleared = true;
+        this.timeSync('clear source-symbol cache', () => this.sourceParserRuntime.clear());
+    }
+    project() {
+        this.projectPromise ??= this.time('analyze Markdown project', () => analyzeMarkdownProject(this.latticeDir, this.projectRoot, {
+            executor: this.executor,
+            onFileAnalyzed: (analysis) => this.recordAnalysis(analysis),
+            onParserImport: (event) => this.recordParserImport(event),
+        }));
+        return this.projectPromise;
+    }
+    async entries() {
+        return (await this.project()).entries;
+    }
+    async markdownFiles() {
+        return (await this.project()).markdownFiles;
+    }
+    async file(file) {
+        const analysis = (await this.project()).filesByAbsolutePath.get(file);
+        if (analysis)
+            return analysis;
+        let auxiliary = this.auxiliaryFilePromises.get(file);
+        if (!auxiliary) {
+            auxiliary = (async () => {
+                const result = await analyzeMarkdownPath(file, this.latticeDir, this.projectRoot, true, (event) => this.recordParserImport(event));
+                this.recordAnalysis(result);
+                return result;
+            })();
+            this.auxiliaryFilePromises.set(file, auxiliary);
+        }
+        return auxiliary;
+    }
+    async content(file) {
+        return (await this.file(file)).content;
+    }
+    async sections(file) {
+        return (await this.file(file)).sections;
+    }
+    async refs(file) {
+        return (await this.file(file)).wikiRefs;
+    }
+    async links(file) {
+        return (await this.file(file)).validationLinks;
+    }
+    async frontmatter(file) {
+        return (await this.file(file)).frontmatter;
+    }
+    async diagnostics(file) {
+        return (await this.file(file)).diagnostics;
+    }
+    async allSections() {
+        return (await this.project()).allSections;
+    }
+    async sectionIndex() {
+        const project = await this.project();
+        return {
+            sectionIds: new Set(project.sectionIds),
+            fileIndex: project.fileIndex,
+            slugIndex: project.slugIndex,
+        };
+    }
+    headings(file) {
+        let headings = this.headingPromises.get(file);
+        if (!headings) {
+            headings = (async () => {
+                const sections = await this.sections(file);
+                return this.timeSync('collect Markdown headings', () => new Set(flattenSections(sections).map((section) => section.githubSlug)), (await this.file(file)).path);
+            })();
+            this.headingPromises.set(file, headings);
+        }
+        return headings;
+    }
+    codeRefs() {
+        this.codeRefsPromise ??= this.time('scan project files for @lat references', () => scanCodeRefs(this.projectRoot, this.profile));
+        return this.codeRefsPromise;
+    }
+    loadExternalResolver() {
+        this.externalResolverPromise ??= this.time('load external-source configuration', () => createExternalResolver(this.latticeDir, this.projectRoot, {
+            onDocumentAnalyzed: (analysis) => this.recordExternalDocumentAnalysis(analysis),
+            onParserImport: (event) => this.recordParserImport(event),
+        }));
+        return this.externalResolverPromise;
+    }
+    async externalResolver() {
+        const resolver = await this.loadExternalResolver();
+        this.reconciledExternalPromise ??= this.time('reconcile external cache', () => resolver.reconcile());
+        await this.reconciledExternalPromise;
+        return resolver;
+    }
+    resolveExternal(target) {
+        let content = this.externalContentPromises.get(target);
+        if (!content) {
+            content = this.time('resolve external reference', async () => (await this.externalResolver()).resolve(target), target);
+            this.externalContentPromises.set(target, content);
+        }
+        return content;
+    }
+    resolveRepositoryLink(target, resolveLink) {
+        let error = this.repositoryLinkErrorPromises.get(target);
+        if (!error) {
+            error = this.time('resolve repository wiki link', resolveLink, target);
+            this.repositoryLinkErrorPromises.set(target, error);
+        }
+        return error;
+    }
+}

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

@@ -1,9 +1,9 @@
 import { readFile } from 'node:fs/promises';
 import { relative } from 'node:path';
-import { scanCodeRefs } from '../code-refs.js';
+import { createCodeReferenceDiscovery } from '../code-refs.js';
 import { listLatticeFiles } from '../lattice.js';
 import { indexNameFor } from './check-mode.js';
-import { toPosix } from '../walk.js';
+import { toPosix } from '../path.js';
 import { basename, dirname } from 'node:path';
 /**
  * Fail a `lat.md/` tree that has documents and no `@lat:` ref pointing into it
@@ -35,10 +35,14 @@ export async function checkCoverage(latticeDir, projectRoot = dirname(latticeDir
     const documents = files.filter((f) => !isIndex(latticeDir, f));
     if (documents.length === 0)
         return [];
-    const scan = await scanCodeRefs(projectRoot);
-    if (scan.files.length === 0)
+    // One discovery for both questions: it coalesces the repeated call and
+    // shares the ripgrep exclusion scan between them. Upstream's ScanResult no
+    // longer carries the file list, so the scope has to be asked for separately.
+    const discovery = createCodeReferenceDiscovery(projectRoot);
+    const { refs } = await discovery.scan();
+    if (refs.length > 0)
         return [];
-    if (scan.refs.length > 0)
+    if ((await discovery.listSourceFiles()).length === 0)
         return [];
     const rootIndexPath = `${latticeDir}/${indexNameFor(basename(latticeDir))}`;
     const rootIndexRel = toPosix(relative(process.cwd(), rootIndexPath));

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

@@ -1,7 +1,7 @@
 import { readFile } from 'node:fs/promises';
 import { dirname, relative } from 'node:path';
 import { listLatticeFiles, parseFrontmatter } from '../lattice.js';
-import { toPosix } from '../walk.js';
+import { toPosix } from '../path.js';
 /**
  * Report frontmatter that parses to nothing useful, or that puts a lat field
  * somewhere the parser will not look.

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

@@ -3,7 +3,7 @@ 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';
+import { toPosix } from '../path.js';
 export const DIATAXIS_MODES = [
     'tutorial',
     'how-to',
@@ -95,12 +95,40 @@ function inlineTextOf(node) {
     })
         .join('');
 }
+/**
+ * A GFM table that the parser handed back as a paragraph.
+ *
+ * `src/parser.ts` runs remark without `remark-gfm`, so a pipe table is never a
+ * `table` node — its rows arrive as one paragraph and every reference document
+ * containing a table failed with "this is a second paragraph", while the error
+ * text told the author to use a table. Adding the plugin would mean editing an
+ * upstream file and changing what `remarkStringify` emits for the whole tool,
+ * which `tests/roundtrip` pins; recognising the shape here costs nothing
+ * outside this check.
+ *
+ * The signature is a delimiter row — `| --- | :--: |` — under a line that opens
+ * a row. Both are required, because a delimiter row is what separates a table
+ * from prose that merely contains pipes.
+ */
+function isPipeTable(node, lines) {
+    const start = node.position?.start.line;
+    const end = node.position?.end.line;
+    if (!start || !end || end - start < 1)
+        return false;
+    const rows = lines.slice(start - 1, end);
+    return rows.some((row, i) => i > 0 &&
+        /^\s*\|?(?:\s*:?-{3,}:?\s*\|)+\s*:?-{3,}:?\s*\|?\s*$/.test(row) &&
+        rows[i - 1].trimStart().startsWith('|'));
+}
 /**
  * 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.
+ *
+ * A pipe table is not prose and never counts, in either position: it is
+ * neither the leading summary a reference is allowed nor an offender.
  */
-function extraParagraphs(tree) {
+function extraParagraphs(tree, lines) {
     const offenders = [];
     let currentHeading = null;
     let seenParagraphUnderHeading = false;
@@ -111,6 +139,8 @@ function extraParagraphs(tree) {
             continue;
         }
         if (node.type === 'paragraph') {
+            if (isPipeTable(node, lines))
+                continue;
             if (currentHeading === null) {
                 // Document lead paragraph before any heading — allowed.
                 continue;
@@ -329,7 +359,7 @@ export async function checkMode(latticeDir, projectRoot = dirname(latticeDir), o
             continue;
         }
         if (mode === 'reference') {
-            for (const offender of extraParagraphs(tree)) {
+            for (const offender of extraParagraphs(tree, content.split('\n'))) {
                 errors.push({
                     file: relPath,
                     line: offender.line,

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

@@ -2,7 +2,7 @@ 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 { toPosix } from '../path.js';
 import { quoteUntrusted } from '../untrusted.js';
 import { fencedLineMask } from './gen-index.js';
 /**

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

@@ -1,4 +1,6 @@
+import type { ResolveSourceSymbolOptions } from '../source-parser.js';
 import type { CmdContext, CmdResult } from '../context.js';
+import { CheckRunContext } from './check-context.js';
 export type CheckError = {
     file: string;
     line: number;
@@ -7,20 +9,17 @@ export type CheckError = {
 };
 /** Format an ambiguous-ref error as structured markdown-like text. */
 export declare function ambiguousRefMessage(target: string, candidates: string[], suggested: string | null): string;
-/** File counts grouped by extension (e.g. { ".ts": 5, ".py": 2 }). */
-export type FileStats = Record<string, number>;
 export type CheckResult = {
     errors: CheckError[];
-    files: FileStats;
 };
 /**
- * Try resolving a wiki link target as a source code reference.
- * Returns null if the reference is valid, or an error message string.
+ * Validate an unresolved wiki link as a repository path or source symbol.
+ * Returns null when valid, otherwise a user-facing error message.
  */
-export declare function sourceRefError(target: string, projectRoot: string): Promise<string | null>;
-export declare function checkMd(latticeDir: string, projectRoot?: string): Promise<CheckResult>;
-export declare function checkLinks(latticeDir: string): Promise<CheckError[]>;
-export declare function checkCodeRefs(latticeDir: string, projectRoot?: string): Promise<CheckResult>;
+export declare function repositoryRefError(target: string, projectRoot: string, sourceOptions?: ResolveSourceSymbolOptions): Promise<string | null>;
+export declare function checkMd(latticeDir: string, projectRoot?: string, context?: CheckRunContext): Promise<CheckResult>;
+export declare function checkLinks(latticeDir: string, context?: CheckRunContext): Promise<CheckError[]>;
+export declare function checkCodeRefs(latticeDir: string, projectRoot?: string, context?: CheckRunContext): Promise<CheckResult>;
 export type IndexError = {
     dir: string;
     message: string;
@@ -33,9 +32,17 @@ export type CheckIndexOptions = {
      */
     fix?: boolean;
 };
-export declare function checkIndex(latticeDir: string, opts?: CheckIndexOptions): Promise<IndexError[]>;
-export declare function checkSections(latticeDir: string, projectRoot?: string): Promise<CheckError[]>;
-export declare function checkAllCommand(ctx: CmdContext, opts?: CheckIndexOptions): Promise<CmdResult>;
+export declare function checkIndex(latticeDir: string, context?: CheckRunContext, opts?: CheckIndexOptions): Promise<IndexError[]>;
+export declare function checkSections(latticeDir: string, projectRoot?: string, context?: CheckRunContext): Promise<CheckError[]>;
+export type CheckCommandOptions = {
+    profile?: boolean;
+    /**
+     * Generate/rewrite index files instead of reporting errors for them.
+     * Non-.md-file errors are still reported — --fix only ever writes markdown.
+     */
+    fix?: boolean;
+};
+export declare function checkAllCommand(ctx: CmdContext, options?: CheckCommandOptions): Promise<CmdResult>;
 export declare function checkMdCommand(ctx: CmdContext): Promise<CmdResult>;
 export declare function checkLinksCommand(ctx: CmdContext): Promise<CmdResult>;
 export declare function checkCodeRefsCommand(ctx: CmdContext): Promise<CmdResult>;