obsidian-second-brain 0.1.1 → 0.2.0

package/dist/code-classify.js

@@ -0,0 +1,150 @@
+import { lstat, readdir, readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { hashContent } from "./changeset.js";
+import { compareBytewise } from "./code-boundaries.js";
+import { hashEvidenceBody, parseCodeEvidence } from "./code-frontmatter.js";
+import { buildSourceKey } from "./manifest.js";
+import { isSlug } from "./slug.js";
+export const CODE_PROVIDER = "code";
+export function codeSourceKey(kind, project, slug) {
+    return buildSourceKey({
+        provider: CODE_PROVIDER,
+        sessionId: kind === "module" ? `${project}/${slug ?? ""}` : project,
+        type: kind
+    });
+}
+export async function scanCodeEvidence(rawCodeRoot) {
+    let projectEntries;
+    try {
+        projectEntries = (await readdir(rawCodeRoot)).sort(compareBytewise);
+    }
+    catch (error) {
+        if (isMissingFileError(error)) {
+            return { quarantined: [], sources: [] };
+        }
+        throw error;
+    }
+    const quarantined = [];
+    const sources = [];
+    for (const project of projectEntries) {
+        if (!isSlug(project)) {
+            continue;
+        }
+        const projectDir = join(rawCodeRoot, project);
+        if (!(await isRealDirectory(projectDir))) {
+            continue;
+        }
+        await readEvidenceFile(join(projectDir, "skeleton.md"), project, "skeleton", undefined, sources, quarantined);
+        let moduleFiles = [];
+        try {
+            moduleFiles = (await readdir(join(projectDir, "modules"))).sort(compareBytewise);
+        }
+        catch (error) {
+            if (!isMissingFileError(error)) {
+                throw error;
+            }
+        }
+        for (const entry of moduleFiles) {
+            if (!entry.endsWith(".md")) {
+                continue;
+            }
+            const slug = entry.slice(0, -3);
+            if (!isSlug(slug) || slug === "overview") {
+                quarantined.push({
+                    contentHash: hashContent(`badslug:${projectDir}/${entry}`),
+                    path: join(projectDir, "modules", entry),
+                    reason: `Invalid module slug in evidence filename: ${entry}`
+                });
+                continue;
+            }
+            await readEvidenceFile(join(projectDir, "modules", entry), project, "module", slug, sources, quarantined);
+        }
+    }
+    return { quarantined, sources };
+}
+// --force support (design 7, codex F6): select entries by DECODED segments,
+// never by raw string prefix on encoded keys — no other provider's state can
+// match provider === "code".
+export function stripCodeManifestEntries(manifest, project) {
+    const entries = Object.fromEntries(Object.entries(manifest.entries).filter(([key]) => !isCodeEntryForProject(key, project)));
+    return { entries, version: manifest.version };
+}
+function isCodeEntryForProject(key, project) {
+    const segments = key.split(":");
+    if (segments.length !== 3) {
+        return false;
+    }
+    let decoded;
+    try {
+        decoded = segments.map((segment) => decodeURIComponent(segment));
+    }
+    catch {
+        return false;
+    }
+    const [provider, , sessionId] = decoded;
+    return (provider === CODE_PROVIDER &&
+        (sessionId === project || sessionId.startsWith(`${project}/`)));
+}
+async function readEvidenceFile(path, project, kind, slug, sources, quarantined) {
+    let stat;
+    try {
+        stat = await lstat(path);
+    }
+    catch (error) {
+        if (isMissingFileError(error)) {
+            return;
+        }
+        throw error;
+    }
+    if (stat.isSymbolicLink()) {
+        quarantined.push({
+            contentHash: hashContent(`symlink:${path}`),
+            path,
+            reason: "Refused symlinked evidence"
+        });
+        return;
+    }
+    let content = "";
+    try {
+        content = await readFile(path, "utf8");
+        const parsed = parseCodeEvidence(content);
+        if (parsed.frontmatter.project !== project) {
+            throw new Error(`Evidence project "${parsed.frontmatter.project}" does not match directory "${project}"`);
+        }
+        if (kind === "module" && parsed.frontmatter.module !== slug) {
+            throw new Error(`Evidence module "${parsed.frontmatter.module ?? ""}" does not match filename "${slug ?? ""}"`);
+        }
+        sources.push({
+            body: parsed.body,
+            bodyHash: hashEvidenceBody(content),
+            frontmatter: parsed.frontmatter,
+            key: codeSourceKey(kind, project, slug),
+            kind,
+            path,
+            project,
+            ...(slug === undefined ? {} : { slug })
+        });
+    }
+    catch (error) {
+        quarantined.push({
+            contentHash: hashContent(`${path}\n${content}`),
+            path,
+            reason: error instanceof Error ? error.message : "Unknown error"
+        });
+    }
+}
+async function isRealDirectory(path) {
+    try {
+        const stat = await lstat(path);
+        return stat.isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+function isMissingFileError(error) {
+    return (error instanceof Error &&
+        "code" in error &&
+        typeof error.code === "string" &&
+        error.code === "ENOENT");
+}

package/dist/code-evidence.js

@@ -0,0 +1,113 @@
+import { compareBytewise } from "./code-boundaries.js";
+export const DIGEST_BUDGET_BYTES = 150_000;
+// Files at or under this embed whole; larger ones contribute their head.
+const FULL_TEXT_BYTES = 8192;
+const HEAD_BYTES = 4096;
+const TOP_ACTIVITY_LIMIT = 20;
+const EXTENSION_LIMIT = 15;
+export function buildSkeletonBody(input) {
+    const { modules, scan } = input;
+    const lines = [];
+    lines.push("## Layout", "");
+    if (input.scope !== undefined) {
+        lines.push(`Scope: \`${input.scope}\``, "");
+    }
+    lines.push(`Tracked files (post-exclusion): ${scan.files.length} (${scan.excludedCount} excluded)`, `Last commit: ${scan.lastCommitDate}`, "");
+    const topLevel = new Map();
+    for (const file of scan.files) {
+        const slashIndex = file.path.indexOf("/");
+        const key = slashIndex === -1 ? "(root)" : file.path.slice(0, slashIndex);
+        const entry = topLevel.get(key) ?? { bytes: 0, count: 0 };
+        topLevel.set(key, { bytes: entry.bytes + file.size, count: entry.count + 1 });
+    }
+    lines.push("| directory | files | bytes |", "|---|---|---|");
+    for (const [name, entry] of [...topLevel.entries()].sort((a, b) => compareBytewise(a[0], b[0]))) {
+        lines.push(`| ${name} | ${entry.count} | ${entry.bytes} |`);
+    }
+    lines.push("", "## Extensions", "");
+    const extensions = new Map();
+    for (const file of scan.files) {
+        const filename = file.path.split("/").at(-1) ?? "";
+        const dotIndex = filename.lastIndexOf(".");
+        const extension = dotIndex > 0 ? filename.slice(dotIndex + 1) : "(none)";
+        extensions.set(extension, (extensions.get(extension) ?? 0) + 1);
+    }
+    const topExtensions = [...extensions.entries()]
+        .sort((a, b) => b[1] - a[1] || compareBytewise(a[0], b[0]))
+        .slice(0, EXTENSION_LIMIT);
+    for (const [extension, count] of topExtensions) {
+        lines.push(`- ${extension}: ${count}`);
+    }
+    lines.push("", "## Modules", "");
+    for (const module of modules) {
+        lines.push(`- ${module.slug} — ${module.files.length} files (${module.name})`);
+    }
+    if (scan.manifests.length > 0) {
+        lines.push("", "## Manifests");
+        for (const manifest of scan.manifests) {
+            lines.push("", `### ${manifest.path}`, "", "````", manifest.text.trim(), "````");
+        }
+    }
+    if (scan.docs.length > 0) {
+        lines.push("", "## Docs");
+        for (const doc of scan.docs) {
+            lines.push("", `### ${doc.path}`, "", "````", doc.text.trim(), "````");
+        }
+    }
+    lines.push("", "## Activity", "");
+    const recent = [...scan.activity.entries()]
+        .sort((a, b) => compareBytewise(b[1], a[1]) || compareBytewise(a[0], b[0]))
+        .slice(0, TOP_ACTIVITY_LIMIT);
+    if (recent.length === 0) {
+        lines.push("No commits in the last 90 days.");
+    }
+    else {
+        for (const [path, date] of recent) {
+            lines.push(`- ${path} — ${date}`);
+        }
+    }
+    return lines.join("\n");
+}
+export async function buildModuleDigestBody(input) {
+    const files = [...input.files].sort((a, b) => compareBytewise(a.path, b.path));
+    const lines = ["## Files", "", "| path | bytes | last-touched |", "|---|---|---|"];
+    for (const file of files) {
+        lines.push(`| ${file.path} | ${file.size} | ${input.activity.get(file.path) ?? "-"} |`);
+    }
+    lines.push("", "## Contents");
+    let spent = Buffer.byteLength(lines.join("\n"), "utf8");
+    let omitted = 0;
+    for (const file of files) {
+        if (omitted > 0) {
+            // Once the budget is hit, stop adding texts entirely — a deterministic
+            // cut, not a best-fit packing.
+            omitted += 1;
+            continue;
+        }
+        const text = await input.readText(file.path);
+        const section = text === undefined
+            ? ["", `### ${file.path} [unreadable]`]
+            : [
+                "",
+                `### ${file.path}`,
+                "",
+                "````",
+                file.size <= FULL_TEXT_BYTES
+                    ? text.trimEnd()
+                    : `${text.slice(0, HEAD_BYTES).trimEnd()}\n[truncated]`,
+                "````"
+            ];
+        const sectionBytes = Buffer.byteLength(section.join("\n"), "utf8");
+        if (spent + sectionBytes > input.budgetBytes) {
+            omitted += 1;
+            continue;
+        }
+        lines.push(...section);
+        spent += sectionBytes;
+    }
+    if (omitted > 0) {
+        lines.push("", `[budget exhausted: ${omitted} file texts omitted]`);
+        return { body: lines.join("\n"), coverage: "partial" };
+    }
+    return { body: lines.join("\n") };
+}

package/dist/code-frontmatter.js

@@ -0,0 +1,147 @@
+import { z } from "zod";
+import { hashContent } from "./changeset.js";
+import { isSlug } from "./slug.js";
+const shaPattern = /^[0-9a-f]{40}$/u;
+const datePattern = /^\d{4}-\d{2}-\d{2}$/u;
+const codeEvidenceSchema = z
+    .object({
+    captured: z.string().regex(datePattern),
+    commit: z.string().regex(shaPattern),
+    coverage: z.literal("partial").optional(),
+    module: z.string().refine(isSlug).optional(),
+    paths: z.array(z.string().min(1)).optional(),
+    project: z.string().refine(isSlug),
+    repo: z.string().min(1)
+})
+    .superRefine((value, context) => {
+    if ((value.module === undefined) !== (value.paths === undefined)) {
+        context.addIssue({
+            code: z.ZodIssueCode.custom,
+            message: "module and paths must both be present (digest) or both absent (skeleton)"
+        });
+    }
+});
+const codePageSchema = z.object({
+    coverage: z.literal("partial").optional(),
+    generated: z.string().regex(datePattern),
+    module: z.string().refine(isSlug).optional(),
+    project: z.string().refine(isSlug),
+    source_commit: z.string().regex(shaPattern),
+    type: z.literal("code-map")
+});
+export const GENERATED_PAGE_COMMENT = "<!-- Generated by second-brain map — manual edits will be overwritten on the next render -->";
+export function parseCodeEvidence(content) {
+    const { body, fields } = splitFrontmatter(content);
+    return {
+        body,
+        frontmatter: codeEvidenceSchema.parse({
+            ...fields,
+            ...(fields.paths === undefined ? {} : { paths: parseJsonArray(fields.paths) })
+        })
+    };
+}
+export function parseCodePage(content) {
+    const { body, fields } = splitFrontmatter(content);
+    return { body, frontmatter: codePageSchema.parse(fields) };
+}
+// Self-healing reads (design 6.3): a page that does not parse is simply not
+// ours / not healthy — the caller decides between re-render and hands-off.
+export function tryParseCodePage(content) {
+    try {
+        return parseCodePage(content);
+    }
+    catch {
+        return undefined;
+    }
+}
+// The hash covers ONLY the body below the fence: provenance churn in
+// commit/captured must never re-trigger renders (design 6.2).
+export function hashEvidenceBody(content) {
+    return hashContent(splitFrontmatter(content).body);
+}
+export function renderCodeEvidence(frontmatter, body) {
+    const lines = [
+        "---",
+        `project: ${frontmatter.project}`,
+        `repo: ${JSON.stringify(frontmatter.repo)}`,
+        `commit: ${frontmatter.commit}`,
+        `captured: ${frontmatter.captured}`
+    ];
+    if (frontmatter.module !== undefined) {
+        lines.push(`module: ${frontmatter.module}`);
+    }
+    if (frontmatter.paths !== undefined) {
+        lines.push(`paths: ${JSON.stringify(frontmatter.paths)}`);
+    }
+    if (frontmatter.coverage !== undefined) {
+        lines.push(`coverage: ${frontmatter.coverage}`);
+    }
+    lines.push("---", "", body.trim(), "");
+    return lines.join("\n");
+}
+export function renderCodePage(frontmatter, body) {
+    const lines = ["---", `project: ${frontmatter.project}`, "type: code-map"];
+    if (frontmatter.module !== undefined) {
+        lines.push(`module: ${frontmatter.module}`);
+    }
+    lines.push(`source_commit: ${frontmatter.source_commit}`, `generated: ${frontmatter.generated}`);
+    if (frontmatter.coverage !== undefined) {
+        lines.push(`coverage: ${frontmatter.coverage}`);
+    }
+    lines.push("---", "", GENERATED_PAGE_COMMENT, "", body.trim(), "");
+    return lines.join("\n");
+}
+// Same dialect as artifact-frontmatter.ts: flat "key: value" lines, BOM and
+// CRLF tolerant, duplicate keys rejected. Values that need structure (paths,
+// repo) are JSON — valid YAML, trivially parseable.
+function splitFrontmatter(content) {
+    const lines = content.replace(/^/u, "").split(/\r?\n/u);
+    if (lines[0] !== "---") {
+        throw new Error("Missing opening frontmatter fence");
+    }
+    const closingIndex = lines.indexOf("---", 1);
+    if (closingIndex === -1) {
+        throw new Error("Missing closing frontmatter fence");
+    }
+    const fields = {};
+    for (const line of lines.slice(1, closingIndex)) {
+        if (line.trim().length === 0) {
+            continue;
+        }
+        const separatorIndex = line.indexOf(":");
+        if (separatorIndex === -1) {
+            throw new Error(`Malformed frontmatter line: ${line}`);
+        }
+        const key = line.slice(0, separatorIndex).trim();
+        if (Object.hasOwn(fields, key)) {
+            throw new Error(`Duplicate frontmatter key: ${key}`);
+        }
+        fields[key] = unquote(line.slice(separatorIndex + 1).trim());
+    }
+    return {
+        body: lines.slice(closingIndex + 1).join("\n").replace(/^\n+/u, "").replace(/\n+$/u, ""),
+        fields
+    };
+}
+function unquote(value) {
+    if (value.startsWith('"') && value.endsWith('"') && value.length >= 2) {
+        try {
+            const parsed = JSON.parse(value);
+            if (typeof parsed === "string") {
+                return parsed;
+            }
+        }
+        catch {
+            // Not JSON after all — keep the raw value.
+        }
+    }
+    return value;
+}
+function parseJsonArray(value) {
+    try {
+        return JSON.parse(value);
+    }
+    catch {
+        throw new Error(`paths is not a JSON array: ${value.slice(0, 80)}`);
+    }
+}