@plebeiantech/lat.md 0.12.3-fork.17 → 0.12.3-fork.20

package/dist/src/lattice.js

@@ -1,353 +0,0 @@
-import { readFile } from 'node:fs/promises';
-import { dirname, basename, relative } from 'node:path';
-import GithubSlugger from 'github-slugger';
-import { parse as parseYaml } from 'yaml';
-import { parse } from './parser.js';
-import { toPosix } from './path.js';
-import { visit } from 'unist-util-visit';
-import { listLatticeFiles } from './project-discovery.js';
-import { flattenSections, } from './lattice-model.js';
-import { LAT_FIELDS, } from './fork/frontmatter-fields.js';
-export { buildFileIndex, buildSectionSlugIndex, findSections, flattenSections, resolveRef, } from './lattice-model.js';
-export { findLatticeDir, findProjectRoot, listLatticeFiles, } from './project-discovery.js';
-export { LAT_FIELDS } from './fork/frontmatter-fields.js';
-export function parseFrontmatter(content) {
-    const match = content.match(/^---\n([\s\S]*?)\n---/);
-    if (!match)
-        return { raw: {} };
-    let raw = {};
-    const problems = [];
-    try {
-        const parsed = parseYaml(match[1]);
-        if (parsed !== null &&
-            typeof parsed === 'object' &&
-            !Array.isArray(parsed)) {
-            const root = parsed;
-            const lat = root['lat'];
-            const hasLatMapping = lat !== null && typeof lat === 'object' && !Array.isArray(lat);
-            if (hasLatMapping) {
-                raw = lat;
-            }
-            // A field written at the document root was accepted by the regex reader
-            // this parser replaced. Staying quiet about it is what makes the change
-            // dangerous: the field simply stops being read.
-            for (const field of LAT_FIELDS) {
-                if (Object.hasOwn(root, field) && !Object.hasOwn(raw, field)) {
-                    problems.push({ kind: 'root-level-field', field });
-                }
-            }
-        }
-    }
-    catch (err) {
-        // One malformed line anywhere in the block used to be harmless, because
-        // the old reader pattern-matched the raw text. A strict parse throws away
-        // every field instead, so the failure has to be reported rather than
-        // swallowed.
-        raw = {};
-        problems.push({
-            kind: 'parse-error',
-            message: err.message.split('\n')[0],
-        });
-    }
-    const result = { raw };
-    if (raw['require-code-mention'] === true) {
-        result.requireCodeMention = true;
-    }
-    if (problems.length > 0)
-        result.problems = problems;
-    return result;
-}
-/** Extract the rendered text GitHub uses as input to its heading slugger. */
-function headingText(node) {
-    if (!node || typeof node !== 'object')
-        return '';
-    const value = node;
-    if (value.type === 'text' || value.type === 'inlineCode') {
-        return value.value ?? '';
-    }
-    if (value.type === 'image' || value.type === 'imageReference') {
-        return value.alt ?? '';
-    }
-    if (value.type === 'wikiLink') {
-        return value.data?.alias ?? value.value ?? '';
-    }
-    if (value.children) {
-        return value.children.map(headingText).join('');
-    }
-    return '';
-}
-function inlineText(node) {
-    return node.children
-        .map((c) => {
-        if (c.type === 'text')
-            return c.value;
-        if (c.type === 'inlineCode')
-            return '`' + c.value + '`';
-        if (c.type === 'wikiLink')
-            return '[[' + c.value + ']]';
-        if ('children' in c)
-            return inlineText(c);
-        return '';
-    })
-        .join('');
-}
-function lastLine(content) {
-    const lines = content.split('\n');
-    // If trailing newline, count doesn't include empty last line
-    return lines[lines.length - 1] === '' ? lines.length - 1 : lines.length;
-}
-export function parseSections(filePath, content, projectRoot, tree = parse(content)) {
-    const file = projectRoot
-        ? toPosix(relative(projectRoot, filePath)).replace(/\.md$/, '')
-        : basename(filePath, '.md');
-    const sectionFilePath = projectRoot
-        ? toPosix(relative(projectRoot, filePath))
-        : basename(filePath);
-    const roots = [];
-    const stack = [];
-    const flat = [];
-    const slugger = new GithubSlugger();
-    const usedIds = new Set();
-    const nextSuffix = new Map();
-    visit(tree, 'heading', (node) => {
-        const heading = headingText(node);
-        const depth = node.depth;
-        const startLine = node.position.start.line;
-        // Pop stack until we find a parent with smaller depth
-        while (stack.length > 0 && stack[stack.length - 1].depth >= depth) {
-            stack.pop();
-        }
-        const parent = stack.length > 0 ? stack[stack.length - 1] : null;
-        const baseId = parent ? `${parent.id}#${heading}` : `${file}#${heading}`;
-        let id = baseId;
-        const key = baseId.toLowerCase();
-        let suffix = nextSuffix.get(key) ?? 1;
-        while (usedIds.has(id.toLowerCase()))
-            id = `${baseId}-${suffix++}`;
-        nextSuffix.set(key, suffix);
-        usedIds.add(id.toLowerCase());
-        const section = {
-            id,
-            heading,
-            depth,
-            file,
-            filePath: sectionFilePath,
-            children: [],
-            startLine,
-            endLine: 0,
-            firstParagraph: '',
-            githubSlug: slugger.slug(headingText(node)),
-        };
-        if (parent) {
-            parent.children.push(section);
-        }
-        else {
-            roots.push(section);
-        }
-        stack.push(section);
-        flat.push(section);
-    });
-    // Compute endLine: line before next heading or last line of file
-    const fileLastLine = lastLine(content);
-    for (let i = 0; i < flat.length; i++) {
-        if (i + 1 < flat.length) {
-            flat[i].endLine = flat[i + 1].startLine - 1;
-        }
-        else {
-            flat[i].endLine = fileLastLine;
-        }
-    }
-    // Extract firstParagraph: first paragraph after each heading
-    const children = tree.children;
-    let headingIdx = 0;
-    for (let i = 0; i < children.length; i++) {
-        const node = children[i];
-        if (node.type === 'heading') {
-            // Find the first paragraph after this heading, before the next heading
-            for (let j = i + 1; j < children.length; j++) {
-                if (children[j].type === 'heading')
-                    break;
-                if (children[j].type === 'paragraph') {
-                    flat[headingIdx].firstParagraph = inlineText(children[j]);
-                    break;
-                }
-            }
-            headingIdx++;
-        }
-    }
-    return roots;
-}
-export async function loadAllSections(latticeDir, projectRoot = dirname(latticeDir), profile) {
-    const files = profile
-        ? await profile.time('list Markdown files', () => listLatticeFiles(latticeDir))
-        : await listLatticeFiles(latticeDir);
-    const all = [];
-    for (const file of files) {
-        const detail = toPosix(relative(latticeDir, file));
-        const content = profile
-            ? await profile.time('read Markdown file', () => readFile(file, 'utf-8'), detail)
-            : await readFile(file, 'utf-8');
-        const sections = profile
-            ? profile.timeSync('parse Markdown sections', () => parseSections(file, content, projectRoot), detail)
-            : parseSections(file, content, projectRoot);
-        all.push(...sections);
-    }
-    return all;
-}
-export function extractRefs(filePath, content, projectRoot, tree = parse(content), sections = parseSections(filePath, content, projectRoot, tree)) {
-    const file = projectRoot
-        ? toPosix(relative(projectRoot, filePath)).replace(/\.md$/, '')
-        : basename(filePath, '.md');
-    const refs = [];
-    // Reuse canonical identities, including duplicate suffixes and formatted text.
-    const flat = flattenSections(sections);
-    visit(tree, 'wikiLink', (node) => {
-        const line = node.position.start.line;
-        // Find enclosing section: last heading with startLine <= link line
-        let fromSection = '';
-        for (const s of flat) {
-            if (s.startLine <= line) {
-                fromSection = s.id;
-            }
-            else {
-                break;
-            }
-        }
-        refs.push({
-            target: node.value,
-            fromSection,
-            file,
-            line,
-        });
-    });
-    return refs;
-}
-function isEscapedAt(value, index) {
-    let slashes = 0;
-    for (let i = index - 1; i >= 0 && value[i] === '\\'; i--)
-        slashes++;
-    return slashes % 2 === 1;
-}
-function closingBracket(value, open) {
-    let depth = 0;
-    for (let i = open; i < value.length; i++) {
-        if (isEscapedAt(value, i))
-            continue;
-        if (value[i] === '[') {
-            depth++;
-        }
-        else if (value[i] === ']') {
-            depth--;
-            if (depth === 0)
-                return i;
-        }
-    }
-    return -1;
-}
-/** Extract link destinations and undefined reference syntax. */
-export function extractLinks(content, tree = parse(content)) {
-    const links = [];
-    visit(tree, ['link', 'image', 'definition'], (node) => {
-        const { url, type, position } = node;
-        links.push({ url, kind: type, line: position.start.line });
-    });
-    // CommonMark parses a reference with no matching definition as plain text,
-    // so it has no linkReference node to visit. Scan the authored syntax while
-    // excluding AST ranges where bracket text is data rather than prose.
-    const excluded = [];
-    visit(tree, [
-        'code',
-        'inlineCode',
-        'html',
-        'math',
-        'inlineMath',
-        'yaml',
-        'link',
-        'image',
-        'definition',
-        'linkReference',
-        'imageReference',
-        'footnoteReference',
-        'alertMarker',
-        'wikiLink',
-    ], (node) => {
-        const start = node.position?.start.offset;
-        const end = node.position?.end.offset;
-        if (start !== undefined && end !== undefined) {
-            excluded.push({ start, end });
-        }
-    });
-    // GFM removes task-list markers from the paragraph AST. Exclude just the
-    // marker prefix so strict shortcut checks still apply to the item body.
-    visit(tree, 'listItem', (node) => {
-        if (typeof node.checked !== 'boolean')
-            return;
-        const start = node.position?.start.offset;
-        const bodyStart = node.children[0]?.position?.start.offset;
-        if (start === undefined || bodyStart === undefined)
-            return;
-        const marker = /\[[ xX]\]/.exec(content.slice(start, bodyStart));
-        if (marker) {
-            excluded.push({
-                start: start + marker.index,
-                end: start + marker.index + marker[0].length,
-            });
-        }
-    });
-    // Likewise, exclude only a footnote definition's label and delimiter. Its
-    // body remains prose and must still obey strict shortcut validation.
-    visit(tree, 'footnoteDefinition', (node) => {
-        const start = node.position?.start.offset;
-        const bodyStart = node.children[0]?.position?.start.offset;
-        if (start !== undefined && bodyStart !== undefined) {
-            excluded.push({ start, end: bodyStart });
-        }
-    });
-    const overlapsExcluded = (start, end) => excluded.some((range) => start < range.end && end > range.start);
-    for (let open = 0; open < content.length; open++) {
-        if (content[open] !== '[' || isEscapedAt(content, open))
-            continue;
-        const labelEnd = closingBracket(content, open);
-        if (labelEnd === -1)
-            continue;
-        const identifierStart = labelEnd + 1;
-        const hasSecondLabel = content[identifierStart] === '[' &&
-            !isEscapedAt(content, identifierStart);
-        const identifierEnd = hasSecondLabel
-            ? closingBracket(content, identifierStart)
-            : labelEnd;
-        if (identifierEnd === -1)
-            continue;
-        const isImage = open > 0 && content[open - 1] === '!' && !isEscapedAt(content, open - 1);
-        const isMalformedDefinition = !isImage && !hasSecondLabel && content[labelEnd + 1] === ':';
-        const start = isImage ? open - 1 : open;
-        const end = identifierEnd + 1 + (isMalformedDefinition ? 1 : 0);
-        if (overlapsExcluded(start, end)) {
-            open = identifierEnd;
-            continue;
-        }
-        const explicitIdentifier = hasSecondLabel
-            ? content.slice(identifierStart + 1, identifierEnd)
-            : '';
-        const identifier = explicitIdentifier || content.slice(open + 1, labelEnd);
-        if (identifier.trim() === '') {
-            open = identifierEnd;
-            continue;
-        }
-        links.push({
-            identifier: identifier.trim(),
-            source: content.slice(start, end),
-            kind: isImage ? 'imageReference' : 'linkReference',
-            style: !hasSecondLabel
-                ? isMalformedDefinition
-                    ? 'definition'
-                    : 'shortcut'
-                : explicitIdentifier
-                    ? 'full'
-                    : 'collapsed',
-            line: content.slice(0, start).split('\n').length,
-        });
-        open = identifierEnd;
-    }
-    return links.sort((a, b) => a.line - b.line);
-}

package/dist/src/markdown-analysis-cache.d.ts

@@ -1,20 +0,0 @@
-import type { MarkdownAnalysisTimings, MarkdownFileAnalysis } from './markdown-analysis.js';
-import type { ParserImportObserver } from './parser-import.js';
-export { PARSER_CACHE_VERSION } from './parser-cache.js';
-export type MarkdownAnalysisCacheStatus = 'disabled' | 'hit' | 'miss';
-export type PreparedMarkdownAnalysis = {
-    absolutePath: string;
-    cachePath: string;
-    content: string;
-    contentHash: string;
-    analysis?: MarkdownFileAnalysis;
-    timings: Pick<MarkdownAnalysisTimings, 'readMs' | 'hashMs' | 'cacheReadMs' | 'cacheStatus'>;
-};
-/** Return the collision-safe, sharded cache path for one Markdown file. */
-export declare function markdownAnalysisCachePath(latDir: string, projectRoot: string, absolutePath: string): string;
-/** Read, hash, and attempt to hydrate one Markdown file from persistent cache. */
-export declare function prepareMarkdownAnalysis(absolutePath: string, latDir: string, projectRoot: string, cache?: boolean): Promise<PreparedMarkdownAnalysis>;
-/** Attach I/O timings and best-effort publish one newly parsed analysis. */
-export declare function publishMarkdownAnalysis(prepared: PreparedMarkdownAnalysis, analysis: MarkdownFileAnalysis): Promise<MarkdownFileAnalysis>;
-/** Analyze one path through the same persistent cache used by project runs. */
-export declare function analyzeMarkdownPath(absolutePath: string, latDir: string, projectRoot: string, cache?: boolean, onParserImport?: ParserImportObserver): Promise<MarkdownFileAnalysis>;

package/dist/src/markdown-analysis-cache.js

@@ -1,139 +0,0 @@
-import { readFile } from 'node:fs/promises';
-import { relative } from 'node:path';
-import { performance } from 'node:perf_hooks';
-import { PARSER_CACHE_VERSION, hashParserContent, parsedCachePath, parserCacheIdentity, readParsedCache, writeParsedCache, } from './parser-cache.js';
-import { toPosix } from './path.js';
-import { loadMarkdownAnalyzer } from './markdown-analyzer-loader.js';
-export { PARSER_CACHE_VERSION } from './parser-cache.js';
-/** Return the collision-safe, sharded cache path for one Markdown file. */
-export function markdownAnalysisCachePath(latDir, projectRoot, absolutePath) {
-    return parsedCachePath(latDir, parserCacheIdentity(absolutePath, projectRoot));
-}
-function emptyTimings(values) {
-    return {
-        ...values,
-        cacheWriteMs: 0,
-        parseMs: 0,
-        sectionsMs: 0,
-        refsMs: 0,
-        linksMs: 0,
-        paragraphsMs: 0,
-        frontmatterMs: 0,
-        indexEntriesMs: 0,
-        diagnosticsMs: 0,
-    };
-}
-function isRecord(value) {
-    return typeof value === 'object' && value !== null && !Array.isArray(value);
-}
-function cachedAnalysis(entry, contentHash, content, absolutePath, latDir, projectRoot) {
-    if (!entry ||
-        entry.version !== PARSER_CACHE_VERSION ||
-        entry.contentHash !== contentHash) {
-        return null;
-    }
-    try {
-        const analysis = entry.value;
-        const expectedPath = toPosix(relative(latDir, absolutePath));
-        const expectedProjectPath = toPosix(relative(projectRoot, absolutePath));
-        if (!isRecord(analysis) ||
-            analysis.content !== content ||
-            analysis.path !== expectedPath ||
-            analysis.projectPath !== expectedProjectPath ||
-            !isRecord(analysis.frontmatter) ||
-            !Array.isArray(analysis.sections) ||
-            !Array.isArray(analysis.headingTitles) ||
-            !Array.isArray(analysis.wikiRefs) ||
-            !Array.isArray(analysis.paragraphs) ||
-            !Array.isArray(analysis.markdownLinks) ||
-            !Array.isArray(analysis.validationLinks) ||
-            !Array.isArray(analysis.indexEntries) ||
-            !Array.isArray(analysis.diagnostics)) {
-            return null;
-        }
-        return { ...analysis, absolutePath };
-    }
-    catch {
-        return null;
-    }
-}
-/** Read, hash, and attempt to hydrate one Markdown file from persistent cache. */
-export async function prepareMarkdownAnalysis(absolutePath, latDir, projectRoot, cache = true) {
-    const cachePath = markdownAnalysisCachePath(latDir, projectRoot, absolutePath);
-    const readStarted = performance.now();
-    const contentPromise = readFile(absolutePath, 'utf8').then((content) => ({
-        content,
-        readMs: performance.now() - readStarted,
-    }));
-    const cacheStarted = performance.now();
-    const cachePromise = cache
-        ? readParsedCache(cachePath).then((entry) => ({
-            entry,
-            cacheReadMs: performance.now() - cacheStarted,
-        }))
-        : Promise.resolve({ entry: null, cacheReadMs: 0 });
-    const [{ content, readMs }, { entry, cacheReadMs }] = await Promise.all([
-        contentPromise,
-        cachePromise,
-    ]);
-    const hashStarted = performance.now();
-    const contentHash = hashParserContent(content);
-    const hashMs = performance.now() - hashStarted;
-    const analysis = cache
-        ? cachedAnalysis(entry, contentHash, content, absolutePath, latDir, projectRoot)
-        : null;
-    const timings = {
-        readMs,
-        hashMs,
-        cacheReadMs,
-        cacheStatus: cache ? (analysis ? 'hit' : 'miss') : 'disabled',
-    };
-    return {
-        absolutePath,
-        cachePath,
-        content,
-        contentHash,
-        analysis: analysis
-            ? { ...analysis, timings: emptyTimings(timings) }
-            : undefined,
-        timings,
-    };
-}
-/** Attach I/O timings and best-effort publish one newly parsed analysis. */
-export async function publishMarkdownAnalysis(prepared, analysis) {
-    const base = {
-        ...analysis,
-        timings: {
-            ...analysis.timings,
-            ...prepared.timings,
-            cacheWriteMs: 0,
-        },
-    };
-    if (prepared.timings.cacheStatus === 'disabled')
-        return base;
-    const started = performance.now();
-    try {
-        await writeParsedCache(prepared.cachePath, prepared.contentHash, base);
-    }
-    catch {
-        // The cache is a disposable optimization; analysis must work read-only.
-    }
-    base.timings.cacheWriteMs = performance.now() - started;
-    return base;
-}
-/** Analyze one path through the same persistent cache used by project runs. */
-export async function analyzeMarkdownPath(absolutePath, latDir, projectRoot, cache = true, onParserImport) {
-    const prepared = await prepareMarkdownAnalysis(absolutePath, latDir, projectRoot, cache);
-    const detail = toPosix(relative(latDir, absolutePath));
-    if (prepared.analysis) {
-        onParserImport?.({
-            parser: 'Markdown analyzer',
-            imported: false,
-            durationMs: 0,
-            detail: `${detail} cached`,
-        });
-        return prepared.analysis;
-    }
-    const analyzeMarkdownFile = await loadMarkdownAnalyzer(onParserImport, detail);
-    return publishMarkdownAnalysis(prepared, analyzeMarkdownFile(absolutePath, prepared.content, latDir, projectRoot));
-}

package/dist/src/markdown-analysis-worker.d.ts

@@ -1,16 +0,0 @@
-import type { MarkdownFileAnalysis } from './markdown-analysis.js';
-export type MarkdownWorkerTask = {
-    id: number;
-    absolutePath: string;
-    content: string;
-    latDir: string;
-    projectRoot: string;
-};
-export type MarkdownWorkerResponse = {
-    id: number;
-    analysis: MarkdownFileAnalysis;
-    importMs?: number;
-} | {
-    id: number;
-    error: string;
-};

package/dist/src/markdown-analysis-worker.js

@@ -1,33 +0,0 @@
-import { parentPort } from 'node:worker_threads';
-import { performance } from 'node:perf_hooks';
-if (!parentPort)
-    throw new Error('Markdown analysis worker needs a parent port');
-async function loadAnalyzer() {
-    const started = performance.now();
-    const sourceRuntime = import.meta.url.endsWith('.ts');
-    const moduleUrl = new URL(sourceRuntime ? './markdown-analysis.ts' : './markdown-analysis.js', import.meta.url).href;
-    const module = sourceRuntime
-        ? await import('tsx/esm/api').then(({ tsImport }) => tsImport(moduleUrl, import.meta.url))
-        : await import(moduleUrl);
-    return {
-        analyzeMarkdownFile: module.analyzeMarkdownFile,
-        importMs: performance.now() - started,
-    };
-}
-const analyzerPromise = loadAnalyzer();
-let importReported = false;
-parentPort.on('message', async (task) => {
-    try {
-        const loaded = await analyzerPromise;
-        const importMs = importReported ? undefined : loaded.importMs;
-        importReported = true;
-        const analysis = loaded.analyzeMarkdownFile(task.absolutePath, task.content, task.latDir, task.projectRoot);
-        parentPort.postMessage({ id: task.id, analysis, importMs });
-    }
-    catch (error) {
-        parentPort.postMessage({
-            id: task.id,
-            error: error instanceof Error ? error.message : String(error),
-        });
-    }
-});

package/dist/src/markdown-analysis.d.ts

@@ -1,61 +0,0 @@
-import type { LatFrontmatter, MdLink, Ref, Section } from './lattice-model.js';
-import { type LocalMarkdownDiagnostic } from './markdown-validation.js';
-export type MarkdownParagraph = {
-    markdown: string;
-    startLine: number;
-    endLine: number;
-    text: string;
-};
-/** Source-positioned block facts; never retains the parser AST. */
-export type MarkdownBlock = {
-    type: string;
-    start: number;
-    end: number;
-    startLine: number;
-    endLine: number;
-    language?: string;
-    children: MarkdownBlock[];
-};
-export type MarkdownDestinationLink = {
-    kind: 'image' | 'link';
-    line: number;
-    url: string;
-};
-export type MarkdownAnalysisTimings = {
-    readMs: number;
-    hashMs: number;
-    cacheReadMs: number;
-    cacheWriteMs: number;
-    cacheStatus: 'disabled' | 'hit' | 'miss';
-    parseMs: number;
-    sectionsMs: number;
-    refsMs: number;
-    linksMs: number;
-    paragraphsMs: number;
-    frontmatterMs: number;
-    indexEntriesMs: number;
-    diagnosticsMs: number;
-};
-/** Serializable semantic facts extracted from one Markdown file. */
-export type MarkdownFileAnalysis = {
-    absolutePath: string;
-    content: string;
-    path: string;
-    projectPath: string;
-    frontmatter: LatFrontmatter;
-    sections: Section[];
-    headingTitles: string[];
-    wikiRefs: Ref[];
-    paragraphs: MarkdownParagraph[];
-    blocks: MarkdownBlock[];
-    markdownLinks: MarkdownDestinationLink[];
-    validationLinks: MdLink[];
-    indexEntries: string[];
-    diagnostics: LocalMarkdownDiagnostic[];
-    timings: MarkdownAnalysisTimings;
-};
-/**
- * Parse and analyze one Markdown document. The syntax tree is deliberately
- * confined to this call so callers and workers only exchange serializable facts.
- */
-export declare function analyzeMarkdownFile(absolutePath: string, content: string, latDir: string, projectRoot: string): MarkdownFileAnalysis;