@dmthepm/commune 0.1.0

package/lib/cli/gate.js

@@ -0,0 +1,165 @@
+/**
+ * `commune gate` — the build check, as a verb.
+ *
+ * This is the one command in the CLI whose exit code answers a question about
+ * your *content* rather than about the command. Everywhere else the contract is
+ * "0 means I finished, findings or not", precisely so an agent can tell a dirty
+ * vault from a broken tool. A gate inverts that on purpose: its whole job is to
+ * stop a build, and a build stops on a non-zero exit. `usage.ts` says so out
+ * loud, because a reader who has internalised the rule needs to be told where
+ * the exception is.
+ *
+ * It was `scripts/test-search-index.mjs`, which imported the graph core by
+ * relative path. That works from a checkout and is unreachable from
+ * `node_modules`, so the one repo that most needs this check — a wiki built
+ * with the package — was the one repo that could not run it. The three
+ * assertions are unchanged; only the way you invoke them is.
+ *
+ * Three assertions:
+ *   1. every page in the `pages` collection is present in the search index
+ *   2. every WikiLink that resolves uses the target's exact title (no pipes,
+ *      no case drift) — the canonical-title rule
+ *   3. WikiLinks pointing at standalone pages actually render as hrefs
+ *
+ * The canonical-title rule itself lives in the graph core, where `commune
+ * check` reports it as a `noncanonical-title` finding. This verb is the *gate*:
+ * same rule, same findings, but a build that violates it stops. Two copies of
+ * one rule is the bug #3 was opened to kill, so there is only ever one.
+ */
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+import { findNoncanonicalTitles, loadContentEntries, stripCode, } from "../lib/graph.js";
+import { EXIT_FAILED, EXIT_OK, failure } from "./errors.js";
+import { SCHEMA, writeJson } from "./render.js";
+const WIKILINK = /\[\[([^\]|]+)(?:\|[^\]]+)?\]\]/g;
+async function readSearchIndex(root) {
+    // The public artifact, not the built one: `public/backlinks.json` is what
+    // the site imports at build time and what both repos commit, so it is the
+    // copy whose staleness would actually ship.
+    const file = path.join(root, 'public', 'backlinks.json');
+    try {
+        return JSON.parse(await readFile(file, 'utf8'));
+    }
+    catch (error) {
+        throw failure('ENOCONTENT', `could not read the search index at ${file}: ${error instanceof Error ? error.message : String(error)}. ` +
+            '`commune gate` runs after a build, which is what writes it.');
+    }
+}
+/** 1. Every standalone page made it into the search index. */
+function pagesAreIndexed(pages, index) {
+    const missing = [];
+    for (const page of pages) {
+        const indexed = index[page.urlPath];
+        if (!indexed || indexed.title !== page.title || indexed.collection !== 'pages') {
+            missing.push(`${page.urlPath} (${page.title})`);
+        }
+    }
+    if (!missing.length)
+        return [];
+    return [
+        {
+            assertion: 'pages-indexed',
+            message: `standalone pages missing from search index: ${missing.join(', ')}`,
+        },
+    ];
+}
+/**
+ * 2. WikiLinks must name their target exactly.
+ *
+ * A piped link or a near-miss title still renders, which is what makes this
+ * worth checking: it fails silently and quietly decouples the vault from the
+ * site.
+ */
+function titlesAreCanonical(entries) {
+    const noncanonical = findNoncanonicalTitles(entries);
+    if (!noncanonical.length)
+        return [];
+    return [
+        {
+            assertion: 'canonical-titles',
+            message: `WikiLinks must use exact page titles:\n${noncanonical
+                .map((finding) => `${finding.file}: ${finding.message}`)
+                .join('\n')}`,
+        },
+    ];
+}
+/**
+ * 3. A note that links to a standalone page must actually render that href.
+ *
+ * The one assertion that catches a resolver regression rather than a content
+ * mistake, and the only one that needs the built output.
+ */
+async function pageLinksRender(entries, pages, dist) {
+    const pageTargets = new Map();
+    for (const page of pages) {
+        pageTargets.set(page.title.toLowerCase(), page.urlPath);
+        for (const alias of page.aliases) {
+            pageTargets.set(alias.toLowerCase(), page.urlPath);
+        }
+    }
+    const unresolved = [];
+    for (const entry of entries) {
+        if (entry.collection !== 'notes')
+            continue;
+        const expected = new Set();
+        for (const match of stripCode(entry.body).matchAll(WIKILINK)) {
+            const url = pageTargets.get(match[1].trim().toLowerCase());
+            if (url)
+                expected.add(url);
+        }
+        if (!expected.size)
+            continue;
+        const page = path.join(dist, 'notes', entry.slug, 'index.html');
+        let html;
+        try {
+            html = await readFile(page, 'utf8');
+        }
+        catch {
+            // A page that links to a standalone page and has no built output has
+            // failed this assertion as surely as one whose href is wrong — and
+            // saying which file is missing beats an ENOENT stack.
+            unresolved.push(`${entry.slug} -> ${page} was not built`);
+            continue;
+        }
+        for (const url of expected) {
+            if (!html.includes(`href="${url}"`))
+                unresolved.push(`${entry.slug} -> ${url}`);
+        }
+    }
+    if (!unresolved.length)
+        return [];
+    return [
+        {
+            assertion: 'page-links-rendered',
+            message: `WikiLinks to standalone pages did not render: ${unresolved.join(', ')}`,
+        },
+    ];
+}
+export async function gateCommand(root, dist, json) {
+    const index = await readSearchIndex(root);
+    const entries = await loadContentEntries({ root });
+    const pages = entries.filter((entry) => entry.collection === 'pages');
+    const distDir = path.resolve(root, dist);
+    // All three run, rather than stopping at the first: a build that broke two
+    // things should say so once, not across two rebuilds.
+    const failures = [
+        ...pagesAreIndexed(pages, index),
+        ...titlesAreCanonical(entries),
+        ...(await pageLinksRender(entries, pages, distDir)),
+    ];
+    const passed = failures.length === 0;
+    const summary = `${pages.length} standalone page${pages.length === 1 ? '' : 's'} indexed for search and linked from notes`;
+    if (json) {
+        writeJson({ schema: SCHEMA, passed, failures });
+    }
+    else {
+        // Both verdicts go to stderr, not just the failing one. A gate's output
+        // is a diagnostic either way, and keeping stdout empty is what lets
+        // `commune gate` sit in a build pipeline without polluting it.
+        for (const found of failures)
+            process.stderr.write(`FAIL: ${found.message}\n`);
+        if (passed)
+            process.stderr.write(`PASS: ${summary}\n`);
+    }
+    return passed ? EXIT_OK : EXIT_FAILED;
+}

package/lib/cli/main.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Argument parsing and dispatch.
+ *
+ * `node:util.parseArgs` has no notion of subcommands, so routing is two passes
+ * over the same argv. The first is non-strict and only looks for positionals —
+ * enough to learn that this is `graph query` — while still consuming `--root`'s
+ * value correctly, since declared string options keep their type even in
+ * non-strict mode. The second pass is strict against that subcommand's schema,
+ * which is what turns a typo into exit 2 instead of a silently ignored flag.
+ *
+ * Being non-strict first is also what lets a parse *failure* be rendered as
+ * JSON: `--json` is known before the strict parse that rejects the argv.
+ */
+/**
+ * Run the CLI and return its exit code.
+ *
+ * Returns rather than calls `process.exit`, so a buffered stdout write is never
+ * truncated by the process going away underneath it.
+ */
+export declare function run(args: string[]): Promise<number>;

package/lib/cli/main.js

@@ -0,0 +1,175 @@
+/**
+ * Argument parsing and dispatch.
+ *
+ * `node:util.parseArgs` has no notion of subcommands, so routing is two passes
+ * over the same argv. The first is non-strict and only looks for positionals —
+ * enough to learn that this is `graph query` — while still consuming `--root`'s
+ * value correctly, since declared string options keep their type even in
+ * non-strict mode. The second pass is strict against that subcommand's schema,
+ * which is what turns a typo into exit 2 instead of a silently ignored flag.
+ *
+ * Being non-strict first is also what lets a parse *failure* be rendered as
+ * JSON: `--json` is known before the strict parse that rejects the argv.
+ */
+import { parseArgs } from 'node:util';
+import { CliError, EXIT_OK, EXIT_USAGE, isParseArgsError, usageError } from "./errors.js";
+import { writeError } from "./render.js";
+import { resolveRoot } from "./root.js";
+import { queryCommand } from "./query.js";
+import { checkCommand } from "./check.js";
+import { gateCommand } from "./gate.js";
+import { relatedCommand } from "./related.js";
+import { COMMAND_USAGE, USAGE } from "./usage.js";
+import { readVersion } from "./version.js";
+/** Options understood everywhere, in any position. */
+const GLOBAL = {
+    root: { type: 'string' },
+    json: { type: 'boolean', default: false },
+    help: { type: 'boolean', default: false },
+};
+const QUERY_OPTIONS = {
+    ...GLOBAL,
+    collection: { type: 'string', multiple: true, default: [] },
+    tag: { type: 'string', multiple: true, default: [] },
+    status: { type: 'string' },
+    orphans: { type: 'boolean', default: false },
+    deadends: { type: 'boolean', default: false },
+};
+const GATE_OPTIONS = {
+    ...GLOBAL,
+    dist: { type: 'string' },
+};
+/** Every route, longest first, so `graph query` is matched before a bare `graph`. */
+const ROUTES = ['graph query', 'graph related', 'check', 'gate'];
+/**
+ * Find which command this argv names, without committing to its schema yet.
+ *
+ * Route words are positionals wherever they appear, so `--root x graph query`
+ * and `graph query --root x` route identically — which matters because the two
+ * spellings are equally natural and only one of them can be the documented one.
+ */
+function route(args) {
+    const { positionals, tokens } = parseArgs({
+        args,
+        options: GLOBAL,
+        allowPositionals: true,
+        strict: false,
+        tokens: true,
+    });
+    const indices = tokens.filter((token) => token.kind === 'positional').map((token) => token.index);
+    for (const candidate of ROUTES) {
+        const words = candidate.split(' ');
+        if (words.every((word, i) => positionals[i] === word)) {
+            const consumed = new Set(indices.slice(0, words.length));
+            return { name: candidate, rest: args.filter((_, i) => !consumed.has(i)) };
+        }
+    }
+    if (!positionals.length) {
+        throw usageError('no command given', USAGE);
+    }
+    throw usageError(`unknown command: ${positionals.slice(0, 2).join(' ')}`, USAGE);
+}
+/** Turn `parseArgs`'s typed failures into the CLI's usage error. */
+function parseStrict(args, options, allowPositionals, usage) {
+    try {
+        return parseArgs({ args, options, allowPositionals, strict: true });
+    }
+    catch (error) {
+        if (isParseArgsError(error))
+            throw usageError(error.message, usage);
+        throw error;
+    }
+}
+async function dispatch(args) {
+    const { name, rest } = route(args);
+    const usage = COMMAND_USAGE[name];
+    switch (name) {
+        case 'graph query': {
+            const { values } = parseStrict(rest, QUERY_OPTIONS, false, usage);
+            if (values.help) {
+                process.stdout.write(`${usage}\n`);
+                return EXIT_OK;
+            }
+            const filters = {
+                collections: values.collection,
+                tags: values.tag,
+                status: values.status,
+                orphans: values.orphans,
+                deadends: values.deadends,
+            };
+            return queryCommand(await resolveRoot(values.root), filters, values.json);
+        }
+        case 'graph related': {
+            const { values, positionals } = parseStrict(rest, GLOBAL, true, usage);
+            if (values.help) {
+                process.stdout.write(`${usage}\n`);
+                return EXIT_OK;
+            }
+            if (positionals.length !== 1) {
+                throw usageError(positionals.length
+                    ? `graph related takes one argument, got ${positionals.length}: ${positionals.join(' ')}. A path containing spaces has to be quoted.`
+                    : 'graph related needs a path, a quoted string of text, or - for stdin', usage);
+            }
+            return relatedCommand(await resolveRoot(values.root), positionals[0], values.json);
+        }
+        case 'check': {
+            const { values } = parseStrict(rest, GLOBAL, false, usage);
+            if (values.help) {
+                process.stdout.write(`${usage}\n`);
+                return EXIT_OK;
+            }
+            return checkCommand(await resolveRoot(values.root), values.json);
+        }
+        case 'gate': {
+            const { values } = parseStrict(rest, GATE_OPTIONS, false, usage);
+            if (values.help) {
+                process.stdout.write(`${usage}\n`);
+                return EXIT_OK;
+            }
+            return gateCommand(await resolveRoot(values.root), values.dist ?? 'dist', values.json);
+        }
+        default:
+            throw usageError(`${name} is not implemented yet`, usage);
+    }
+}
+/**
+ * Run the CLI and return its exit code.
+ *
+ * Returns rather than calls `process.exit`, so a buffered stdout write is never
+ * truncated by the process going away underneath it.
+ */
+export async function run(args) {
+    // Read before parsing: the errors most worth emitting as JSON are the ones
+    // thrown by the parse itself.
+    const json = args.includes('--json');
+    try {
+        // Before the route table, not in it: `--version` is a question about the
+        // installed package, not about a project, so it must answer from
+        // anywhere — including a directory with no `src/content` in it, where
+        // every real verb exits 1. Plain stdout and nothing else, because the
+        // thing most likely to read it is a script.
+        //
+        // Read out of argv wherever it appears, like `--json` two lines above
+        // and for the same reason as `--root`: every other flag in this CLI is
+        // position-insensitive, and a `--version` that only worked first would
+        // be the one exception nobody would remember. No `-v` alias — `-v` is
+        // "verbose" in enough tools to be worth not claiming for something else.
+        if (args.includes('--version')) {
+            process.stdout.write(`${await readVersion()}\n`);
+            return EXIT_OK;
+        }
+        if (!args.length || args[0] === '--help' || args[0] === '-h') {
+            process.stdout.write(`${USAGE}\n`);
+            return args.length ? EXIT_OK : EXIT_USAGE;
+        }
+        return await dispatch(args);
+    }
+    catch (error) {
+        if (error instanceof CliError) {
+            writeError(error, json);
+            return error.exitCode;
+        }
+        writeError(new CliError('EINTERNAL', error instanceof Error ? error.message : String(error), 1), json);
+        return 1;
+    }
+}

package/lib/cli/query.d.ts

@@ -0,0 +1,30 @@
+/**
+ * `commune graph query` — the graph as a list of entries.
+ *
+ * Each entry carries its resolved `outbound` and `inbound` urlPaths, so a
+ * consumer gets the whole neighbourhood in one document rather than one call
+ * per note. Filters narrow which entries are *returned*; they never change how
+ * links resolve, so an entry's degree is the same whether or not you filtered.
+ */
+import { type CollectionName } from '../lib/graph.ts';
+export interface QueryFilters {
+    collections: string[];
+    tags: string[];
+    status?: string;
+    orphans: boolean;
+    deadends: boolean;
+}
+export interface QueryEntry {
+    urlPath: string;
+    title: string;
+    collection: CollectionName;
+    file: string;
+    slug: string;
+    tags: string[];
+    status: string;
+    aliases: string[];
+    updated?: string;
+    outbound: string[];
+    inbound: string[];
+}
+export declare function queryCommand(root: string, filters: QueryFilters, json: boolean): Promise<number>;

package/lib/cli/query.js

@@ -0,0 +1,103 @@
+/**
+ * `commune graph query` — the graph as a list of entries.
+ *
+ * Each entry carries its resolved `outbound` and `inbound` urlPaths, so a
+ * consumer gets the whole neighbourhood in one document rather than one call
+ * per note. Filters narrow which entries are *returned*; they never change how
+ * links resolve, so an entry's degree is the same whether or not you filtered.
+ */
+import { buildGraph, loadContentEntries, } from "../lib/graph.js";
+import { SCHEMA, writeJson, writeLines } from "./render.js";
+import { EXIT_OK } from "./errors.js";
+/** Project one loaded entry against the built graph. */
+function toQueryEntry(entry, graph) {
+    const node = graph.nodes[entry.urlPath];
+    return {
+        urlPath: entry.urlPath,
+        title: entry.title,
+        collection: entry.collection,
+        file: entry.file,
+        slug: entry.slug,
+        tags: entry.tags,
+        status: entry.status,
+        aliases: entry.aliases,
+        ...(entry.updated ? { updated: entry.updated } : {}),
+        outbound: node.outbound,
+        inbound: node.inbound,
+    };
+}
+/**
+ * Isolated: nothing links here and this links nowhere.
+ *
+ * Not "nobody links to it" — a note that links out but is linked to by nothing
+ * is a dead end read from the other direction, and conflating the two is what
+ * makes Obsidian's orphan list useless on a vault where most notes link out.
+ * One definition, used by both the filter and the summary, so `--orphans` can
+ * never disagree with `summary.orphans`.
+ */
+function isOrphan(entry) {
+    return entry.inbound.length === 0 && entry.outbound.length === 0;
+}
+/** Links to nothing. Whether anything links *here* is a separate question. */
+function isDeadend(entry) {
+    return entry.outbound.length === 0;
+}
+/**
+ * Repeated values of one flag widen the match; different flags narrow it.
+ *
+ * `--collection notes --collection pages --tag seed` means "a note or a page,
+ * which is also tagged seed" — the reading that lets a caller build up a query
+ * without the flags fighting each other.
+ */
+function matches(entry, filters) {
+    if (filters.collections.length && !filters.collections.includes(entry.collection))
+        return false;
+    if (filters.tags.length && !entry.tags.some((tag) => filters.tags.includes(tag)))
+        return false;
+    if (filters.status !== undefined && entry.status !== filters.status)
+        return false;
+    if (filters.orphans && !isOrphan(entry))
+        return false;
+    if (filters.deadends && !isDeadend(entry))
+        return false;
+    return true;
+}
+/**
+ * What came back, counted.
+ *
+ * Describes the *result set*, not the corpus, so it never contradicts `count`
+ * beside it. Degrees are still whole-graph — filtering changes which entries
+ * are returned, never how their links resolved — so an unfiltered query's
+ * `edges` is the same number `check` reports, counted from the outbound end
+ * rather than the inbound one.
+ *
+ * Free to compute: `outbound` and `inbound` are already materialized on every
+ * node by the time a query can be filtered at all.
+ */
+function summarize(results) {
+    return {
+        entries: results.length,
+        edges: results.reduce((total, entry) => total + entry.outbound.length, 0),
+        orphans: results.filter(isOrphan).length,
+        deadends: results.filter(isDeadend).length,
+    };
+}
+export async function queryCommand(root, filters, json) {
+    const entries = await loadContentEntries({ root });
+    const graph = buildGraph(entries);
+    const results = entries.map((entry) => toQueryEntry(entry, graph)).filter((entry) => matches(entry, filters));
+    const summary = summarize(results);
+    if (json) {
+        // `count` predates `summary` and stays as its alias: the field shipped in
+        // the contract #10 and #19 are written against, and removing it would be
+        // a schema bump for no gain.
+        writeJson({ schema: SCHEMA, root, count: summary.entries, summary, entries: results });
+        return EXIT_OK;
+    }
+    writeLines([
+        ...results.map((entry) => `${entry.urlPath}\t${entry.title}\t${entry.collection}\t${entry.status}\t` +
+            `→${entry.outbound.length} ←${entry.inbound.length}`),
+        `${summary.entries} entries, ${summary.edges} edges, ${summary.orphans} orphans, ${summary.deadends} dead ends`,
+    ]);
+    return EXIT_OK;
+}

package/lib/cli/related.d.ts

@@ -0,0 +1,17 @@
+/**
+ * `commune graph related` — what a piece of text connects to.
+ *
+ * This is the primitive the connect step (#19) and the authoring skills (#10)
+ * are written against, so v1 is deliberately deterministic: two buckets, both
+ * computable from what the core already does, and no ranking.
+ *
+ *   `links`    — every edge the text actually contains, with its resolution.
+ *   `mentions` — entries whose title or alias appears as a whole word in the
+ *                prose, which is the "you wrote about this without linking it"
+ *                signal a connect step needs.
+ *
+ * Fuzzy and semantic similarity are out of scope on purpose. They are product
+ * direction, not a build decision, and inventing a ranking here would freeze it
+ * into the contract before anyone chose it.
+ */
+export declare function relatedCommand(root: string, input: string, json: boolean): Promise<number>;