@plebeiantech/lat.md 0.12.3-fork.13 → 0.12.3-fork.15

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

@@ -1,5 +1,6 @@
-import { type Section, type SectionMatch } from '../lattice.js';
+import { type Section, type SectionMatch } from '../lattice-model.js';
 import type { CmdContext, CmdResult } from '../context.js';
+import type { ResolvedExternalContent } from '../external-sources.js';
 import { type ProvenanceNote } from './check-status.js';
 export type CodeBackRef = {
     file: string;
@@ -24,6 +25,7 @@ export type SectionFound = {
         resolved: Section;
     }[];
     outgoingSourceRefs: SourceRef[];
+    outgoingExternalRefs: ResolvedExternalContent[];
     incomingRefs: SectionMatch[];
     codeRefs: CodeBackRef[];
 };

package/dist/src/cli/section.js

@@ -1,9 +1,12 @@
 import { readFile } from 'node:fs/promises';
 import { extname, join, relative } from 'node:path';
-import { loadAllSections, findSections, flattenSections, extractRefs, buildFileIndex, buildSectionSlugIndex, resolveRef, listLatticeFiles, } from '../lattice.js';
-import { scanCodeRefs } from '../code-refs.js';
-import { SOURCE_EXTENSIONS, resolveSourceSymbol } from '../source-parser.js';
-import { formatSectionId, formatNavHints } from '../format.js';
+import { findSections, flattenSections, resolveRef, } from '../lattice-model.js';
+import { MAX_SECTION_SUMMARY_LENGTH } from '../markdown-validation.js';
+import { resolveSourceSymbol } from '../source-parser.js';
+import { isSourceFileExtension } from '../source-formats.js';
+import { formatNavHints, formatResultList, formatSectionId, } from '../format.js';
+import { findRefs } from './refs.js';
+import { commandProjectAnalysis, commandProjectSession, } from '../project-analysis.js';
 import { provenanceNote, formatProvenanceNote, } from './check-status.js';
 /**
  * Look up a section by id, return its content, outgoing wiki link targets,
@@ -11,8 +14,8 @@ import { provenanceNote, formatProvenanceNote, } from './check-status.js';
  */
 export async function getSection(ctx, query) {
     query = query.replace(/^\[\[|\]\]$/g, '');
-    const allSections = await loadAllSections(ctx.latDir);
-    const matches = findSections(allSections, query);
+    const project = await commandProjectAnalysis(ctx);
+    const matches = findSections(project.allSections, query);
     if (matches.length === 0) {
         return { kind: 'no-match', suggestions: [] };
     }
@@ -27,28 +30,41 @@ export async function getSection(ctx, query) {
     const section = top.section;
     // Read raw content between startLine and the end of the last descendant
     const absPath = join(ctx.projectRoot, section.filePath);
-    const fileContent = await readFile(absPath, 'utf-8');
+    const analyzedFile = project.filesByAbsolutePath.get(absPath);
+    if (!analyzedFile)
+        return { kind: 'no-match', suggestions: [] };
+    const fileContent = analyzedFile.content;
     const lines = fileContent.split('\n');
     const end = fullEndLine(section);
     const content = lines.slice(section.startLine - 1, end).join('\n');
     // Find outgoing wiki link targets within this section's content
-    const flat = flattenSections(allSections);
-    const sectionIds = new Set(flat.map((s) => s.id.toLowerCase()));
-    const fileIndex = buildFileIndex(allSections);
-    const slugIndex = buildSectionSlugIndex(allSections);
-    const sectionRefs = extractRefs(absPath, fileContent, ctx.projectRoot);
+    const flat = project.sections;
+    const sectionIds = new Set(project.sectionIds);
+    const { fileIndex, slugIndex } = project;
     const sectionId = section.id.toLowerCase();
+    const subtreeSections = flattenSections([section]);
+    const subtreeSectionIds = new Set(subtreeSections.map((subtreeSection) => subtreeSection.id.toLowerCase()));
+    const sectionRefs = subtreeSections.flatMap((subtreeSection) => project.outgoingRefsBySection.get(subtreeSection.id.toLowerCase()) ?? []);
     const outgoingRefs = [];
     const outgoingSourceRefs = [];
+    const outgoingExternalRefs = [];
+    const external = await commandProjectSession(ctx).external();
     const seen = new Set();
     for (const ref of sectionRefs) {
-        if (ref.fromSection.toLowerCase() !== sectionId)
+        if (!subtreeSectionIds.has(ref.fromSection.toLowerCase()))
+            continue;
+        if (external.parse(ref.target)) {
+            if (!seen.has(ref.target)) {
+                seen.add(ref.target);
+                outgoingExternalRefs.push(await external.resolve(ref.target));
+            }
             continue;
+        }
         // Detect source code references by file extension
         const hashIdx = ref.target.indexOf('#');
         const filePart = hashIdx === -1 ? ref.target : ref.target.slice(0, hashIdx);
         const ext = extname(filePart);
-        if (SOURCE_EXTENSIONS.has(ext)) {
+        if (isSourceFileExtension(ext)) {
             const targetLower = ref.target.toLowerCase();
             if (!seen.has(targetLower)) {
                 seen.add(targetLower);
@@ -57,7 +73,7 @@ export async function getSection(ctx, query) {
                 let endLine = 0;
                 let snippet = '';
                 if (symbolPart) {
-                    const { found, symbols } = await resolveSourceSymbol(filePart, symbolPart, ctx.projectRoot);
+                    const { found, symbols } = await resolveSourceSymbol(filePart, symbolPart, ctx.projectRoot, commandProjectSession(ctx).sourceSymbolOptions());
                     if (found) {
                         const parts = symbolPart.split('#');
                         const sym = symbols.find((s) => parts.length === 1
@@ -101,31 +117,24 @@ export async function getSection(ctx, query) {
     }
     // Find incoming references: other sections that link to this one
     const incomingRefs = [];
-    const files = await listLatticeFiles(ctx.latDir);
     const incomingSections = new Set();
-    for (const file of files) {
-        const fc = await readFile(file, 'utf-8');
-        const fileRefs = extractRefs(file, fc, ctx.projectRoot);
-        for (const ref of fileRefs) {
-            const { resolved } = resolveRef(ref.target, sectionIds, fileIndex, slugIndex);
-            if (resolved.toLowerCase() === sectionId &&
-                ref.fromSection.toLowerCase() !== sectionId) {
-                if (!incomingSections.has(ref.fromSection.toLowerCase())) {
-                    incomingSections.add(ref.fromSection.toLowerCase());
-                    const fromSection = flat.find((s) => s.id.toLowerCase() === ref.fromSection.toLowerCase());
-                    if (fromSection) {
-                        incomingRefs.push({ section: fromSection, reason: 'wiki link' });
-                    }
-                }
+    for (const ref of project.incomingRefsBySection.get(sectionId) ?? []) {
+        if (ref.fromSection.toLowerCase() === sectionId)
+            continue;
+        if (!incomingSections.has(ref.fromSection.toLowerCase())) {
+            incomingSections.add(ref.fromSection.toLowerCase());
+            const fromSection = project.sectionById.get(ref.fromSection.toLowerCase());
+            if (fromSection) {
+                incomingRefs.push({ section: fromSection, reason: 'wiki link' });
             }
         }
     }
     // Find code back-references: @lat: comments pointing to this section
     const codeRefs = [];
-    const { refs: scannedRefs } = await scanCodeRefs(ctx.projectRoot);
+    const { refs: scannedRefs } = await commandProjectSession(ctx).codeRefs();
     for (const ref of scannedRefs) {
         const { resolved: codeResolved } = resolveRef(ref.target, sectionIds, fileIndex, slugIndex);
-        if (codeResolved.toLowerCase() === sectionId) {
+        if (subtreeSectionIds.has(codeResolved.toLowerCase())) {
             const absFile = join(ctx.projectRoot, ref.file);
             let snippet = '';
             try {
@@ -148,6 +157,7 @@ export async function getSection(ctx, query) {
         status: provenanceNote(fileContent),
         outgoingRefs,
         outgoingSourceRefs,
+        outgoingExternalRefs,
         incomingRefs,
         codeRefs,
     };
@@ -160,12 +170,23 @@ function fullEndLine(section) {
 function truncate(s, max) {
     return s.length > max ? s.slice(0, max) + '...' : s;
 }
+const SECTION_SUMMARY_SAFETY_LIMIT = MAX_SECTION_SUMMARY_LENGTH + 50;
+function sectionSummary(section) {
+    return truncate(section.firstParagraph, SECTION_SUMMARY_SAFETY_LIMIT);
+}
+function markdownInlineCode(value) {
+    const content = value || ' ';
+    const longestBacktickRun = Math.max(0, ...(content.match(/`+/g) ?? []).map((run) => run.length));
+    const delimiter = '`'.repeat(longestBacktickRun + 1);
+    const padded = content.startsWith('`') || content.endsWith('`') ? ` ${content} ` : content;
+    return `${delimiter}${padded}${delimiter}`;
+}
 /**
  * Format a successful section result with styling.
  */
 export function formatSectionOutput(ctx, result) {
     const s = ctx.styler;
-    const { section, content, status, outgoingRefs, outgoingSourceRefs, incomingRefs, codeRefs, } = result;
+    const { section, content, status, outgoingRefs, outgoingSourceRefs, outgoingExternalRefs, incomingRefs, codeRefs, } = result;
     const relPath = relative(process.cwd(), join(ctx.projectRoot, section.filePath));
     const loc = `${s.cyan(relPath)}${s.dim(`:${section.startLine}-${section.endLine}`)}`;
     const quoted = content
@@ -180,11 +201,13 @@ export function formatSectionOutput(ctx, result) {
     if (status)
         parts.push(formatProvenanceNote(status, s));
     parts.push('', quoted);
-    if (outgoingRefs.length > 0 || outgoingSourceRefs.length > 0) {
+    if (outgoingRefs.length > 0 ||
+        outgoingSourceRefs.length > 0 ||
+        outgoingExternalRefs.length > 0) {
         parts.push('', '## This section references:', '');
         for (const ref of outgoingRefs) {
             const body = ref.resolved.firstParagraph
-                ? ` ${s.dim('—')} ${truncate(ref.resolved.firstParagraph, 120)}`
+                ? ` ${s.dim('—')} ${sectionSummary(ref.resolved)}`
                 : '';
             parts.push(`${s.dim('*')} [[${formatSectionId(ref.resolved.id, s)}]]${body}`);
         }
@@ -198,16 +221,22 @@ export function formatSectionOutput(ctx, result) {
             if (ref.snippet) {
                 const snippetLines = ref.snippet.split('\n');
                 for (const line of snippetLines) {
-                    parts.push(`  ${s.dim('|')} ${line}`);
+                    parts.push(`  ${s.dim('|')} ${markdownInlineCode(line)}`);
                 }
             }
         }
+        for (const ref of outgoingExternalRefs) {
+            parts.push(`${s.dim('*')} [[${s.cyan(ref.target.identity)}]]${s.dim(` (${ref.target.repositoryPath}:${ref.startLine}-${ref.endLine}, ${ref.provider})`)}`);
+            for (const line of ref.content.split('\n').slice(0, 5)) {
+                parts.push(`  ${s.dim('|')} ${ref.kind === 'source' ? markdownInlineCode(line) : line}`);
+            }
+        }
     }
     if (incomingRefs.length > 0) {
         parts.push('', '## Referenced by:', '');
         for (const ref of incomingRefs) {
             const body = ref.section.firstParagraph
-                ? ` ${s.dim('—')} ${truncate(ref.section.firstParagraph, 120)}`
+                ? ` ${s.dim('—')} ${sectionSummary(ref.section)}`
                 : '';
             parts.push(`${s.dim('*')} [[${formatSectionId(ref.section.id, s)}]]${body}`);
         }
@@ -220,7 +249,7 @@ export function formatSectionOutput(ctx, result) {
             if (ref.snippet) {
                 const snippetLines = ref.snippet.split('\n');
                 for (const line of snippetLines) {
-                    parts.push(`  ${s.dim('|')} ${line}`);
+                    parts.push(`  ${s.dim('|')} ${markdownInlineCode(line)}`);
                 }
             }
         }
@@ -229,6 +258,53 @@ export function formatSectionOutput(ctx, result) {
     return parts.join('\n');
 }
 export async function sectionCommand(ctx, query) {
+    const external = await commandProjectSession(ctx).external();
+    let externalTarget = null;
+    try {
+        externalTarget = external.parse(query);
+    }
+    catch (error) {
+        return { output: ctx.styler.red(error.message), isError: true };
+    }
+    if (externalTarget) {
+        try {
+            const resolved = await external.resolve(query);
+            const backlinks = await findRefs(ctx, resolved.target.identity, 'md+code');
+            const location = `${resolved.target.handle}:${resolved.target.authoredPath}:${resolved.startLine}-${resolved.endLine}`;
+            const quoted = resolved.content
+                .split('\n')
+                .map((line) => (line ? `> ${line}` : '>'))
+                .join('\n');
+            const warnings = resolved.source.localError
+                ? `\n\n${ctx.styler.yellow(`Warning: ${resolved.source.localError}; using ${resolved.provider}`)}`
+                : '';
+            const parts = [
+                `${ctx.styler.bold(`[[${resolved.target.identity}]]`)} (${ctx.styler.cyan(location)})`,
+                ctx.styler.dim(`${resolved.source.repo} @ ${resolved.source.commit} via ${resolved.provider}`),
+                '',
+                quoted,
+            ];
+            if (backlinks.kind === 'found' && backlinks.mdRefs.length > 0) {
+                parts.push(formatResultList(ctx, `Referenced by Markdown:`, backlinks.mdRefs));
+            }
+            if (backlinks.kind === 'found' && backlinks.codeRefs.length > 0) {
+                parts.push('', '## Referenced by code:', '', ...backlinks.codeRefs.map((value) => `${ctx.styler.dim('*')} ${value}`));
+            }
+            return {
+                output: parts.join('\n') + warnings + formatNavHints(ctx),
+            };
+        }
+        catch (error) {
+            return {
+                output: ctx.styler.red(error.message),
+                isError: true,
+            };
+        }
+    }
+    const unknownExternal = external.unknownTargetMessage(query);
+    if (unknownExternal) {
+        return { output: ctx.styler.red(unknownExternal), isError: true };
+    }
     const result = await getSection(ctx, query);
     if (result.kind === 'no-match') {
         const s = ctx.styler;

package/dist/src/code-refs.d.ts

@@ -1,5 +1,7 @@
-/** Walk project files for code-ref scanning. Uses walkEntries for .gitignore
- *  support, then additionally skips .md files, lat.md/, .claude/, and sub-projects. */
+import type { Profiler } from './profiler.js';
+/** Walk supported source files for code-ref scanning. Uses walkEntries for
+ *  .gitignore support, then additionally skips lat.md/, .claude/, generated
+ *  UI output, and sub-projects. */
 export declare function walkFiles(dir: string): Promise<string[]>;
 export declare const LAT_REF_RE: RegExp;
 export type CodeRef = {
@@ -9,9 +11,19 @@ export type CodeRef = {
 };
 export type ScanResult = {
     refs: CodeRef[];
-    files: string[];
-    usedRg: boolean;
+};
+export type CodeReferenceDiscovery = {
+    scan: () => Promise<ScanResult>;
+    listSourceFiles: () => Promise<string[]>;
 };
 /** Check whether ripgrep (`rg`) is available on PATH. */
 export declare function hasRipgrep(): Promise<boolean>;
-export declare function scanCodeRefs(projectRoot: string): Promise<ScanResult>;
+/**
+ * Create a lazy project-scoped discovery API. Code-reference scanning and
+ * source-file inventory are separate operations, but share ripgrep exclusion
+ * discovery and coalesce fallback file walking when both are requested.
+ */
+export declare function createCodeReferenceDiscovery(projectRoot: string, profile?: Pick<Profiler, 'time'>): CodeReferenceDiscovery;
+export declare function scanCodeRefs(projectRoot: string, profile?: Pick<Profiler, 'time'>): Promise<ScanResult>;
+/** Discover the source files that may contain code references. */
+export declare function discoverSourceFiles(projectRoot: string, profile?: Pick<Profiler, 'time'>): Promise<string[]>;