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

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

@@ -1,215 +0,0 @@
-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.d.ts

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

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

@@ -1,75 +0,0 @@
-import { readFile } from 'node:fs/promises';
-import { relative } from 'node:path';
-import { createCodeReferenceDiscovery } from '../code-refs.js';
-import { listLatticeFiles } from '../lattice.js';
-import { indexNameFor } from './check-mode.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
- * 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 [];
-    // 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 ((await discovery.listSourceFiles()).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-frontmatter.d.ts

@@ -1,12 +0,0 @@
-import type { CheckError } from './check.js';
-/**
- * Report frontmatter that parses to nothing useful, or that puts a lat field
- * somewhere the parser will not look.
- *
- * Both failures are quiet by nature, and both fail OPEN. A misplaced or
- * unparseable `require-code-mention` turns a validation off, and `lat check`
- * then reports success on a file whose leaf sections are no longer required to
- * carry `@lat:` coverage. Nothing else in the output says the rule stopped
- * applying, which is precisely why it has to be said here.
- */
-export declare function checkFrontmatter(latticeDir: string, projectRoot?: string): Promise<CheckError[]>;

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

@@ -1,44 +0,0 @@
-import { readFile } from 'node:fs/promises';
-import { dirname, relative } from 'node:path';
-import { listLatticeFiles, parseFrontmatter } from '../lattice.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.
- *
- * Both failures are quiet by nature, and both fail OPEN. A misplaced or
- * unparseable `require-code-mention` turns a validation off, and `lat check`
- * then reports success on a file whose leaf sections are no longer required to
- * carry `@lat:` coverage. Nothing else in the output says the rule stopped
- * applying, which is precisely why it has to be said here.
- */
-export async function checkFrontmatter(latticeDir, projectRoot = dirname(latticeDir)) {
-    const files = await listLatticeFiles(latticeDir);
-    const errors = [];
-    for (const file of files) {
-        const content = await readFile(file, 'utf-8');
-        const problems = parseFrontmatter(content).problems;
-        if (!problems)
-            continue;
-        const relPath = relative(process.cwd(), file);
-        const target = toPosix(relative(projectRoot, file)).replace(/\.md$/, '');
-        for (const problem of problems) {
-            if (problem.kind === 'root-level-field') {
-                errors.push({
-                    file: relPath,
-                    line: 1,
-                    target,
-                    message: `frontmatter sets "${problem.field}" at the document root, where it is ignored — nest it under "lat:" instead:\n    ---\n    lat:\n      ${problem.field}: ...\n    ---`,
-                });
-                continue;
-            }
-            errors.push({
-                file: relPath,
-                line: 1,
-                target,
-                message: `frontmatter is not valid YAML (${problem.message}) — every lat field in this document is being ignored, including any that turn a check on`,
-            });
-        }
-    }
-    return errors;
-}

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

@@ -1,21 +0,0 @@
-import type { CheckError } from './check.js';
-export declare const DIATAXIS_MODES: readonly ["tutorial", "how-to", "reference", "explanation"];
-export type DiataxisMode = (typeof DIATAXIS_MODES)[number];
-/** Directory below lat.md/ that holds each mode. */
-export declare const MODE_DIRS: Record<DiataxisMode, string>;
-/**
- * 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[]>;