@doxbrix/doxloop 0.1.4 → 0.2.0

package/dist/release-notes.js

@@ -0,0 +1,183 @@
+import { execFile } from 'node:child_process';
+import { readdir, readFile } from 'node:fs/promises';
+import { join, resolve } from 'node:path';
+import { promisify } from 'node:util';
+import { DoxloopError } from './errors.js';
+import { pathExists } from './fs.js';
+import { loadProject, sourceKind } from './project.js';
+const execute = promisify(execFile);
+/**
+ * Deterministic inputs for a release-notes plan: the commits and changed files
+ * between two Git refs of every Git-backed source, plus the section of the
+ * product's own changelog that names the release. The planner and writer get
+ * this inventory verbatim, so the page is grounded in the actual commit range
+ * rather than in what the agent remembers about the product.
+ */
+export const MAX_RELEASE_COMMITS = 200;
+export const MAX_RELEASE_FILES = 300;
+const MAX_BODY_CHARS = 400;
+const MAX_CHANGELOG_CHARS = 6000;
+const CHANGELOG_NAMES = ['changelog', 'changes', 'history', 'releases', 'release-notes', 'news'];
+const SAFE_REF = /^(?!-)[\w./@^~{}+-]{1,120}$/;
+/** Directory sources whose checkout is a Git repository. */
+export async function gitBackedSources(root, project) {
+    const output = [];
+    for (const source of project.sources) {
+        if (sourceKind(source) !== 'directory')
+            continue;
+        if (await isGitRepository(resolve(root, source.path)))
+            output.push(source);
+    }
+    return output;
+}
+export async function listSourceRefs(root, sourceName) {
+    const project = await loadProject(root);
+    const source = project.sources.find((entry) => entry.name === sourceName);
+    if (!source || sourceKind(source) !== 'directory')
+        throw new DoxloopError(`"${sourceName}" is not a directory source.`, 2);
+    const path = resolve(root, source.path);
+    if (!(await isGitRepository(path)))
+        throw new DoxloopError(`"${sourceName}" is not a Git checkout, so it has no release refs.`, 2);
+    // The last sort key is primary: newest first, with version order breaking ties created in the same second.
+    const tags = lines(await git(path, ['tag', '--sort=-version:refname', '--sort=-creatordate', '--merged', 'HEAD'])).slice(0, 100);
+    const branches = lines(await git(path, ['branch', '--format=%(refname:short)'])).slice(0, 50);
+    const head = (await git(path, ['rev-parse', '--short', 'HEAD'])).trim();
+    const suggested = tags.length >= 2
+        ? { from: tags[1], to: tags[0], version: tags[0] }
+        : tags.length === 1
+            ? { from: tags[0], to: 'HEAD', version: `${tags[0]} (unreleased changes)` }
+            : undefined;
+    return { source: source.name, tags, branches, head, ...(suggested ? { suggested } : {}) };
+}
+export async function collectReleaseInventory(root, project, input) {
+    const version = input.version.trim();
+    if (!version || version.length > 60)
+        throw new DoxloopError('Release notes need a version label, such as v0.2.0.', 2);
+    const from = validRef(input.from, 'Starting ref');
+    const to = validRef(input.to, 'Ending ref');
+    const candidates = await gitBackedSources(root, project);
+    const selected = input.sources?.length
+        ? candidates.filter((source) => input.sources.includes(source.name))
+        : candidates;
+    if (selected.length === 0) {
+        throw new DoxloopError(input.sources?.length
+            ? `None of ${input.sources.join(', ')} is a Git-backed directory source.`
+            : 'Release notes need at least one directory source that is a Git checkout. Connect the product repository under Sources first.', 2);
+    }
+    const sources = [];
+    for (const source of selected) {
+        sources.push(await inventorySource(root, source, from, to, version));
+    }
+    return { version, from, to, collectedAt: new Date().toISOString(), sources };
+}
+async function inventorySource(root, source, from, to, version) {
+    const path = resolve(root, source.path);
+    for (const ref of [from, to]) {
+        try {
+            await git(path, ['rev-parse', '--verify', '--quiet', `${ref}^{commit}`]);
+        }
+        catch {
+            throw new DoxloopError(`"${ref}" is not a commit, tag, or branch in source "${source.name}".`, 2);
+        }
+    }
+    const log = await git(path, [
+        'log', '--no-merges', '--date=short', `--max-count=${MAX_RELEASE_COMMITS + 1}`,
+        '--format=%H%x1f%ad%x1f%an%x1f%s%x1f%b%x1e', `${from}..${to}`,
+    ]);
+    const commits = log.split('\x1e').map((entry) => entry.trim()).filter(Boolean).map((entry) => {
+        const [hash = '', date = '', author = '', subject = '', body = ''] = entry.split('\x1f');
+        const trimmedBody = body.trim().replace(/\s+/g, ' ').slice(0, MAX_BODY_CHARS);
+        return { hash: hash.slice(0, 12), date, author, subject: subject.trim(), ...(trimmedBody ? { body: trimmedBody } : {}) };
+    });
+    const truncatedCommits = commits.length > MAX_RELEASE_COMMITS;
+    const diff = lines(await git(path, ['diff', '--name-status', from, to]));
+    const changedFiles = diff.slice(0, MAX_RELEASE_FILES).map((line) => line.replace(/\t+/g, ' '));
+    const changelog = await changelogExcerpt(path, version);
+    return {
+        source: source.name,
+        from,
+        to,
+        commits: commits.slice(0, MAX_RELEASE_COMMITS),
+        changedFiles,
+        truncated: truncatedCommits || diff.length > MAX_RELEASE_FILES,
+        ...(changelog ? { changelog } : {}),
+    };
+}
+/** The changelog section that names the version, or the top of the file when no section matches. */
+export async function changelogExcerpt(sourceRoot, version) {
+    let entries;
+    try {
+        entries = await readdir(sourceRoot);
+    }
+    catch {
+        return undefined;
+    }
+    const file = entries.find((entry) => CHANGELOG_NAMES.includes(entry.replace(/\.(md|mdx|markdown|txt|rst)$/i, '').toLowerCase()));
+    if (!file)
+        return undefined;
+    const text = await readFile(join(sourceRoot, file), 'utf8');
+    return { path: file, excerpt: extractVersionSection(text, version) };
+}
+export function extractVersionSection(text, version) {
+    const lines = text.split(/\r?\n/);
+    const needle = version.replace(/^v/i, '').toLowerCase();
+    const isHeading = (line) => /^#{1,3}\s/.test(line) || /^(?:version|release)\b/i.test(line);
+    const level = (line) => (/^(#{1,3})\s/.exec(line)?.[1]?.length ?? 1);
+    const start = lines.findIndex((line) => isHeading(line) && line.toLowerCase().includes(needle));
+    if (start === -1)
+        return text.slice(0, MAX_CHANGELOG_CHARS);
+    const startLevel = level(lines[start]);
+    let end = lines.length;
+    for (let index = start + 1; index < lines.length; index += 1) {
+        if (isHeading(lines[index]) && level(lines[index]) <= startLevel) {
+            end = index;
+            break;
+        }
+    }
+    return lines.slice(start, end).join('\n').trim().slice(0, MAX_CHANGELOG_CHARS);
+}
+/** The inventory as the planner and writer read it. */
+export function formatReleaseInventory(inventory) {
+    const parts = [`Release: ${inventory.version} (${inventory.from}..${inventory.to}, collected ${inventory.collectedAt.slice(0, 10)})`];
+    for (const source of inventory.sources) {
+        parts.push(`\nSource "${source.source}": ${source.commits.length} commit${source.commits.length === 1 ? '' : 's'}, ${source.changedFiles.length} changed file${source.changedFiles.length === 1 ? '' : 's'}${source.truncated ? ' (truncated)' : ''}`);
+        if (source.changelog)
+            parts.push(`Changelog (${source.changelog.path}):\n${source.changelog.excerpt}`);
+        if (source.commits.length > 0) {
+            parts.push('Commits, newest first:');
+            for (const commit of source.commits)
+                parts.push(`- ${commit.date} ${commit.hash} ${commit.subject}${commit.body ? ` — ${commit.body}` : ''}`);
+        }
+        if (source.changedFiles.length > 0)
+            parts.push(`Changed files:\n${source.changedFiles.map((file) => `- ${file}`).join('\n')}`);
+    }
+    return parts.join('\n');
+}
+export function releaseNotesPagePath(version) {
+    const slug = version.trim().toLowerCase().replace(/^v(?=\d)/, '').replace(/[^a-z0-9.]+/g, '-').replace(/^-+|-+$/g, '') || 'latest';
+    return `release-notes/${slug}`;
+}
+function validRef(value, label) {
+    const ref = value.trim();
+    if (!SAFE_REF.test(ref))
+        throw new DoxloopError(`${label} must be a Git tag, branch, or commit.`, 2);
+    return ref;
+}
+async function isGitRepository(path) {
+    if (!(await pathExists(path)))
+        return false;
+    try {
+        return (await git(path, ['rev-parse', '--is-inside-work-tree'])).trim() === 'true';
+    }
+    catch {
+        return false;
+    }
+}
+async function git(path, args) {
+    const result = await execute('git', ['-C', path, ...args], { maxBuffer: 32 * 1024 * 1024 });
+    return result.stdout;
+}
+function lines(value) {
+    return value.split(/\r?\n/).map((line) => line.trim()).filter(Boolean);
+}
+//# sourceMappingURL=release-notes.js.map

package/dist/remote-monitor.d.ts

@@ -0,0 +1,16 @@
+import type { DoxloopProject, RemoteSource, SourceChange, SyncState } from './types.js';
+export interface RemoteMonitorResult {
+    project: DoxloopProject;
+    changes: SourceChange[];
+    nextState: SyncState;
+}
+/** Verify read access to a configured remote Git branch without downloading source. */
+export declare function testRemoteSource(remote: RemoteSource): Promise<{
+    head: string;
+}>;
+/**
+ * Observe configured product repositories without writing to the user's source
+ * checkout. Managed snapshots live outside the documentation project.
+ */
+export declare function monitorRemoteSources(root: string, project: DoxloopProject): Promise<RemoteMonitorResult>;
+//# sourceMappingURL=remote-monitor.d.ts.map

package/dist/remote-monitor.js

@@ -0,0 +1,74 @@
+import { sourceKind } from './project.js';
+import { changedFilesInRemoteScope, materializeRemoteSource, remoteChangedFiles, remoteHead, } from './remote-source.js';
+import { collectSourceChanges, readSyncState } from './sync.js';
+/** Verify read access to a configured remote Git branch without downloading source. */
+export async function testRemoteSource(remote) {
+    return { head: await remoteHead(remote) };
+}
+/**
+ * Observe configured product repositories without writing to the user's source
+ * checkout. Managed snapshots live outside the documentation project.
+ */
+export async function monitorRemoteSources(root, project) {
+    const previous = await readSyncState(root);
+    const nextState = {
+        schemaVersion: 1,
+        sources: { ...previous.sources },
+    };
+    const changes = [];
+    const sources = [];
+    for (const source of project.sources) {
+        if (sourceKind(source) === 'openapi') {
+            changes.push(...await collectSourceChanges(root, [source]));
+            sources.push(source);
+            continue;
+        }
+        if (!source.remote) {
+            changes.push(...await collectSourceChanges(root, [source]));
+            sources.push(source);
+            continue;
+        }
+        const head = await remoteHead(source.remote);
+        const record = previous.sources[source.name];
+        if (!record) {
+            const snapshot = await materializeRemoteSource(root, source, head);
+            changes.push({ ...source, path: snapshot.path, kind: 'no-baseline', head, uncommittedFiles: [] });
+            sources.push({ ...source, path: snapshot.path });
+            nextState.sources[source.name] = {
+                commit: head,
+                recordedAt: new Date().toISOString(),
+            };
+            continue;
+        }
+        if (record.commit === head) {
+            changes.push({
+                ...source,
+                kind: 'unchanged',
+                baseline: record.commit,
+                head,
+                changedFiles: [],
+                uncommittedFiles: [],
+            });
+            sources.push(source);
+            continue;
+        }
+        const changedFiles = changedFilesInRemoteScope(await remoteChangedFiles(source.remote, record.commit, head), source.remote.subdirectory);
+        const snapshot = await materializeRemoteSource(root, source, head);
+        changes.push({
+            ...source,
+            path: snapshot.path,
+            kind: 'changed',
+            baseline: record.commit,
+            head,
+            changedFiles,
+            uncommittedFiles: [],
+        });
+        sources.push({ ...source, path: snapshot.path });
+        nextState.sources[source.name] = {
+            commit: head,
+            recordedAt: new Date().toISOString(),
+        };
+    }
+    return { project: { ...project, sources }, changes, nextState };
+}
+//# sourceMappingURL=remote-monitor.js.map

package/dist/remote-source.d.ts

@@ -0,0 +1,34 @@
+import type { RemoteSource, SourceBinding } from './types.js';
+export interface GitCredential {
+    username?: string;
+    secret: string;
+}
+export interface RemoteBranch {
+    name: string;
+    head: string;
+}
+/** Validate a provider-neutral Git clone URL without embedding credentials. */
+export declare function parseGitRepository(value: string): string;
+/** Keep private-repository credentials in memory for this Doxloop UI session. */
+export declare function rememberRemoteCredential(repository: string, username: string | undefined, secret: string | undefined): void;
+/**
+ * Forward UI-session credentials to Doxloop child processes without writing
+ * them to the project configuration or placing them on a command line.
+ */
+export declare function remoteCredentialEnvironment(): NodeJS.ProcessEnv;
+/** Accept GitHub web/clone URLs or owner/name and return the canonical slug. */
+export declare function parseGitHubRepository(value: string): string;
+export declare function listRemoteBranches(remote: RemoteSource): Promise<RemoteBranch[]>;
+export declare function remoteHead(remote: RemoteSource): Promise<string>;
+/** List repository folders without checking out file contents. */
+export declare function listRemoteDirectories(remote: RemoteSource): Promise<string[]>;
+export declare function remoteChangedFiles(remote: RemoteSource, baseline: string, head: string): Promise<string[]>;
+/** Download a provider snapshot outside the documentation deployment boundary. */
+export declare function materializeRemoteSource(root: string, source: Pick<SourceBinding, 'name' | 'remote'>, requestedHead?: string): Promise<{
+    path: string;
+    head: string;
+    files: number;
+}>;
+export declare function changedFilesInRemoteScope(files: string[], subdirectory?: string): string[];
+export declare function portableSourcePath(root: string, sourcePath: string): string;
+//# sourceMappingURL=remote-source.d.ts.map