@plebeiantech/lat.md 0.12.3-fork.1 → 0.12.3-fork.10

package/dist/src/code-refs.js

@@ -1,6 +1,6 @@
 import { readFile } from 'node:fs/promises';
 import { execFile } from 'node:child_process';
-import { join, relative } from 'node:path';
+import { join, posix, relative } from 'node:path';
 import { toPosix, walkEntries } from './walk.js';
 /** Glob patterns used to exclude directories/files from code-ref scanning.
  *  Shared between rg args and the TS fallback's walkFiles filter. */
@@ -9,7 +9,10 @@ const EXCLUDE_GLOBS = ['*.md'];
 /** Walk project files for code-ref scanning. Uses walkEntries for .gitignore
  *  support, then additionally skips .md files, lat.md/, .claude/, and sub-projects. */
 export async function walkFiles(dir) {
-    const entries = await walkEntries(dir);
+    const entries = (await walkEntries(dir)).map(toPosix);
+    const generatedOutputs = new Set(entries
+        .filter((entry) => entry.endsWith('/.lat-ui-build'))
+        .map((entry) => `${posix.dirname(entry)}/`));
     // Collect directories that contain their own lat.md/ (sub-projects)
     const subProjects = new Set();
     for (const e of entries) {
@@ -21,6 +24,7 @@ export async function walkFiles(dir) {
         .filter((e) => !e.endsWith('.md') &&
         !e.startsWith('lat.md/') &&
         !e.startsWith('.claude/') &&
+        ![...generatedOutputs].some((prefix) => e.startsWith(prefix)) &&
         ![...subProjects].some((prefix) => e.startsWith(prefix)))
         .map((e) => join(dir, e));
 }
@@ -148,8 +152,22 @@ async function findSubProjects(projectRoot) {
     }
     return [...subProjects];
 }
+/** Find static UI exports so generated JSON and bundles never become code refs. */
+async function findGeneratedOutputs(projectRoot) {
+    const out = await tryExec('rg', ['--files', '--hidden', '--glob', '**/.lat-ui-build', '.'], projectRoot);
+    if (!out)
+        return [];
+    return [
+        ...new Set(out
+            .split('\n')
+            .filter(Boolean)
+            .map((line) => toPosix(line).replace(/^\.\//, ''))
+            .filter((line) => line.endsWith('/.lat-ui-build'))
+            .map((line) => posix.dirname(line))),
+    ];
+}
 /** Build rg glob exclusion args. */
-function rgExcludeArgs(subProjects) {
+function rgExcludeArgs(subProjects, generatedOutputs) {
     const args = [];
     for (const dir of EXCLUDE_DIRS)
         args.push('--glob', `!${dir}/`);
@@ -157,6 +175,8 @@ function rgExcludeArgs(subProjects) {
         args.push('--glob', `!${glob}`);
     for (const sp of subProjects)
         args.push('--glob', `!${sp}/`);
+    for (const output of generatedOutputs)
+        args.push('--glob', `!${output}/`);
     return args;
 }
 /**
@@ -167,7 +187,8 @@ function rgExcludeArgs(subProjects) {
 async function tryRipgrep(projectRoot) {
     // Detect sub-projects first so we can exclude them from all rg calls
     const subProjects = await findSubProjects(projectRoot);
-    const excludes = rgExcludeArgs(subProjects);
+    const generatedOutputs = await findGeneratedOutputs(projectRoot);
+    const excludes = rgExcludeArgs(subProjects, generatedOutputs);
     // Search for @lat refs
     const searchArgs = [
         '--no-heading',

package/dist/src/fork/upstream-drift-cli.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/src/fork/upstream-drift-cli.js

@@ -0,0 +1,2 @@
+import { main } from './upstream-drift.js';
+process.exit(main(process.argv.slice(2)));

package/dist/src/fork/upstream-drift.d.ts

@@ -0,0 +1,26 @@
+export declare const UPSTREAM_URL = "https://github.com/vercel-labs/lat.md.git";
+export declare const UPSTREAM_REF = "refs/remotes/upstream/main";
+export type Drift = {
+    upstream: string;
+    ahead: number;
+    behind: number;
+    upstreamFiles: string[];
+    forkFiles: string[];
+    overlap: string[];
+    conflicts: string[];
+    mergesCleanly: boolean;
+};
+/**
+ * Conflicting paths from `git merge-tree --write-tree --name-only`, whose
+ * output is the written tree id, then one path per line, then a blank line
+ * and the human-readable log. Everything after that blank line is prose.
+ */
+export declare function parseMergeTree(stdout: string): string[];
+export declare function fetchUpstream(repo: string, url: string, ref: string): void;
+export declare function analyzeDrift(opts: {
+    repo: string;
+    syncPoint: string;
+    upstreamRef: string;
+}): Drift;
+export declare function formatDrift(drift: Drift): string;
+export declare function main(argv: string[]): number;

package/dist/src/fork/upstream-drift.js

@@ -0,0 +1,185 @@
+import { spawnSync } from 'node:child_process';
+import { existsSync, readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { parseNameStatus, parseSyncPoint, repoRoot, SYNC_POINT_FILE, } from './upstream-guard.js';
+export const UPSTREAM_URL = 'https://github.com/vercel-labs/lat.md.git';
+export const UPSTREAM_REF = 'refs/remotes/upstream/main';
+function git(repo, args) {
+    const result = spawnSync('git', ['-C', repo, ...args], {
+        encoding: 'utf-8',
+        maxBuffer: 64 * 1024 * 1024,
+    });
+    if (result.error)
+        throw result.error;
+    return result;
+}
+/**
+ * Conflicting paths from `git merge-tree --write-tree --name-only`, whose
+ * output is the written tree id, then one path per line, then a blank line
+ * and the human-readable log. Everything after that blank line is prose.
+ */
+export function parseMergeTree(stdout) {
+    const lines = stdout.split('\n');
+    const paths = [];
+    for (const line of lines.slice(1)) {
+        if (line.trim() === '')
+            break;
+        paths.push(line);
+    }
+    return paths;
+}
+function names(diff) {
+    return [...new Set(diff.map((d) => d.path))].sort();
+}
+function diffNames(repo, from, to) {
+    const result = git(repo, [
+        'diff',
+        '--no-renames',
+        '--name-status',
+        '-z',
+        from,
+        to,
+    ]);
+    if (result.status !== 0) {
+        throw new Error(`git diff ${from}..${to} failed: ${result.stderr.trim()}`);
+    }
+    return names(parseNameStatus(result.stdout));
+}
+function count(repo, range) {
+    const result = git(repo, ['rev-list', '--count', range]);
+    if (result.status !== 0) {
+        throw new Error(`git rev-list ${range} failed: ${result.stderr.trim()}`);
+    }
+    return Number(result.stdout.trim());
+}
+export function fetchUpstream(repo, url, ref) {
+    const result = git(repo, [
+        'fetch',
+        '--no-tags',
+        url,
+        `+refs/heads/main:${ref}`,
+    ]);
+    if (result.status !== 0) {
+        throw new Error(`fetching ${url} failed: ${result.stderr.trim()}`);
+    }
+}
+// @lat: [[fork#Watching the drift]]
+export function analyzeDrift(opts) {
+    const root = repoRoot(opts.repo);
+    const head = git(root, ['rev-parse', 'HEAD']).stdout.trim();
+    const upstream = git(root, ['rev-parse', opts.upstreamRef]).stdout.trim();
+    const upstreamFiles = diffNames(root, opts.syncPoint, upstream);
+    const forkFiles = diffNames(root, opts.syncPoint, head);
+    const forkSet = new Set(forkFiles);
+    const merge = git(root, [
+        'merge-tree',
+        '--write-tree',
+        '--name-only',
+        head,
+        upstream,
+    ]);
+    return {
+        upstream,
+        ahead: count(root, `${opts.syncPoint}..${upstream}`),
+        behind: count(root, `${upstream}..${head}`),
+        upstreamFiles,
+        forkFiles,
+        overlap: upstreamFiles.filter((f) => forkSet.has(f)),
+        conflicts: merge.status === 0 ? [] : parseMergeTree(merge.stdout),
+        mergesCleanly: merge.status === 0,
+    };
+}
+function list(paths) {
+    return paths.map((p) => `- \`${p}\``);
+}
+export function formatDrift(drift) {
+    const lines = [`## Upstream drift`, ''];
+    if (drift.ahead === 0) {
+        lines.push('Upstream has nothing new since the recorded sync point.', '');
+        return lines.join('\n');
+    }
+    lines.push(`Upstream is **${drift.ahead} commit(s)** ahead of the sync point, ` +
+        `touching **${drift.upstreamFiles.length} file(s)**. This fork has ` +
+        `${drift.behind} commit(s) of its own.`, '', `Upstream tip: \`${drift.upstream.slice(0, 12)}\``, '');
+    if (drift.mergesCleanly) {
+        lines.push('Merges without a textual conflict.', '');
+    }
+    else {
+        lines.push(`### ${drift.conflicts.length} conflicting file(s)`, '', ...list(drift.conflicts), '');
+    }
+    // A file both sides changed is where the next conflict comes from, even
+    // when today's merge is clean.
+    lines.push(`### ${drift.overlap.length} file(s) changed on both sides`, '', ...(drift.overlap.length === 0 ? ['None.'] : list(drift.overlap)), '', 'A clean merge is not a working tree. Two additions can collide in the', 'knowledge graph without conflicting in git, and an upstream type can', 'widen underneath a fork-owned test. The job checks both after merging.', '');
+    return lines.join('\n');
+}
+const USAGE = `Usage: node dist/src/fork/upstream-drift-cli.js [options]
+
+  --repo <dir>          default the current working directory
+  --url <git-url>       default ${UPSTREAM_URL}
+  --ref <ref>           default ${UPSTREAM_REF}
+  --sync-point <rev>    default the recorded sync point
+  --no-fetch            use the ref already in the repository
+  --fail-on-conflict    exit 1 when the merge would conflict
+  -h, --help            this text
+`;
+export function main(argv) {
+    const opts = {
+        repo: process.cwd(),
+        url: UPSTREAM_URL,
+        ref: UPSTREAM_REF,
+        syncPoint: '',
+        fetch: true,
+        failOnConflict: false,
+    };
+    for (let i = 0; i < argv.length; i += 1) {
+        const arg = argv[i];
+        if (arg === '-h' || arg === '--help') {
+            process.stdout.write(USAGE);
+            return 0;
+        }
+        else if (arg === '--no-fetch')
+            opts.fetch = false;
+        else if (arg === '--fail-on-conflict')
+            opts.failOnConflict = true;
+        else if (arg === '--repo')
+            opts.repo = argv[++i] ?? '';
+        else if (arg === '--url')
+            opts.url = argv[++i] ?? '';
+        else if (arg === '--ref')
+            opts.ref = argv[++i] ?? '';
+        else if (arg === '--sync-point')
+            opts.syncPoint = argv[++i] ?? '';
+        else {
+            process.stderr.write(`unknown argument: ${arg}\n\n${USAGE}`);
+            return 2;
+        }
+    }
+    try {
+        const root = repoRoot(opts.repo);
+        if (opts.syncPoint === '') {
+            const file = resolve(root, SYNC_POINT_FILE);
+            if (!existsSync(file)) {
+                process.stderr.write(`upstream-drift: no sync point at ${file}\n`);
+                return 2;
+            }
+            opts.syncPoint = parseSyncPoint(readFileSync(file, 'utf-8')) ?? '';
+            if (opts.syncPoint === '') {
+                process.stderr.write(`upstream-drift: ${file} holds no revision\n`);
+                return 2;
+            }
+        }
+        if (opts.fetch)
+            fetchUpstream(root, opts.url, opts.ref);
+        const drift = analyzeDrift({
+            repo: root,
+            syncPoint: opts.syncPoint,
+            upstreamRef: opts.ref,
+        });
+        process.stdout.write(formatDrift(drift));
+        return opts.failOnConflict && !drift.mergesCleanly ? 1 : 0;
+    }
+    catch (error) {
+        process.stderr.write(`upstream-drift: ${error.message}\n`);
+        return 2;
+    }
+}

package/dist/src/fork/upstream-guard-cli.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/src/fork/upstream-guard-cli.js

@@ -0,0 +1,2 @@
+import { main } from './upstream-guard.js';
+process.exit(main(process.argv.slice(2)));

package/dist/src/fork/upstream-guard.d.ts

@@ -0,0 +1,72 @@
+export declare const SYNC_POINT_FILE = "fork-upstream-sync-point";
+/**
+ * The commit this fork was originally cut from. It is not the guard's
+ * baseline — see [[fork#The upstream guard#The sync point]] for why a frozen
+ * one cannot tell the fork's changes from upstream's.
+ */
+export declare const ORIGINAL_FORK_POINT = "65d2f5b220853b2b10dca3de18d511f575bc12c7";
+export declare const ALLOWLIST_FILE = "fork-upstream-allowlist.tsv";
+export declare const REASON_PLACEHOLDER = "TODO";
+export type AllowEntry = {
+    path: string;
+    reason: string;
+    line: number;
+};
+export type ParsedAllowlist = {
+    entries: AllowEntry[];
+    errors: string[];
+};
+export declare function parseAllowlist(text: string): ParsedAllowlist;
+export declare function renderAllowlist(entries: AllowEntry[]): string;
+export declare function needsReason(reason: string): boolean;
+export type DiffEntry = {
+    status: string;
+    path: string;
+};
+export declare function parseNameStatus(raw: string): DiffEntry[];
+export type Finding = {
+    kind: 'deletion' | 'unallowlisted' | 'missing-reason' | 'allowlist-error';
+    path: string;
+    message: string;
+};
+export type ClassifyInput = {
+    diff: DiffEntry[];
+    upstream: ReadonlySet<string>;
+    allowlist: ReadonlyMap<string, string>;
+};
+export type ClassifyResult = {
+    findings: Finding[];
+    warnings: string[];
+    touched: string[];
+};
+export declare function classify(input: ClassifyInput): ClassifyResult;
+export declare function repoRoot(from: string): string;
+export declare function hasCommit(repo: string, rev: string): boolean;
+export declare function diffAgainst(repo: string, rev: string): DiffEntry[];
+export declare function upstreamPaths(repo: string, rev: string, paths: string[]): Set<string>;
+export declare function parseSyncPoint(text: string): string | undefined;
+export declare function renderSyncPoint(previous: string, rev: string): string;
+export declare function isAncestorOfHead(repo: string, rev: string): boolean;
+export declare function isShallow(repo: string): boolean;
+export type GuardOptions = {
+    repo: string;
+    /** Overrides the recorded sync point. Omitted, the file decides. */
+    syncPoint?: string;
+    allowlistFile: string;
+    syncPointFile?: string;
+    regenerate: boolean;
+    fetch: boolean;
+    setSyncPoint?: string;
+};
+export declare function fetchSyncPoint(repo: string, rev: string): boolean;
+export type GuardResult = {
+    ok: boolean;
+    report: string;
+    findings: Finding[];
+    warnings: string[];
+};
+export declare function runGuard(options: GuardOptions): GuardResult;
+export declare function parseArgs(argv: string[]): GuardOptions | {
+    help: true;
+};
+export declare function main(argv: string[]): number;