polydeukes 0.5.0 → 0.6.1

package/dist/docs-library.js

@@ -0,0 +1,347 @@
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { buildDocs as buildDocsImpl, loadDocsBundle } from './docs-catalog.js';
+import { DOCS_TOPICS as topics } from './docs-types.js';
+const rootHelp = `pdks docs\nUsage: pdks docs [topic]\n       pdks docs search <query> [--lang en|ko] [--limit N] [--json]\n       pdks docs show <document-id> [--lang en|ko] [--section <section-id>] [--json]\n\nTopics:\n${topics.map((topic) => `  ${topic}`).join('\n')}\n`;
+function fail(message) {
+    throw new Error(message);
+}
+function isDocumentId(value) {
+    return /^[a-z0-9][a-z0-9-]*$/.test(value);
+}
+function isSectionId(value) {
+    return /^[a-z0-9][a-z0-9-]*$/.test(value);
+}
+function quoteShellWord(value) {
+    return /^[A-Za-z0-9_@%+=:,./-]+$/.test(value) ? value : `'${value.replace(/'/g, `'"'"'`)}'`;
+}
+function shellCommand(parts) {
+    return parts.map(quoteShellWord).join(' ');
+}
+function languageFrom(value) {
+    if (value === 'en' || value === 'ko')
+        return value;
+    fail(`unsupported language: ${value ?? '(missing)'}`);
+}
+function sectionSource(path, sectionId) {
+    return sectionId ? `${path}#${sectionId}` : path;
+}
+function normalizeQuery(value) {
+    const query = value.trim();
+    if (query === '')
+        fail('empty search query');
+    return query;
+}
+function excerptFor(markdown, query) {
+    const needle = query.toLowerCase();
+    const haystack = markdown.toLowerCase();
+    const at = haystack.indexOf(needle);
+    if (at === -1)
+        return markdown.slice(0, 160);
+    const start = Math.max(0, at - 40);
+    const end = Math.min(markdown.length, at + query.length + 80);
+    return markdown.slice(start, end);
+}
+function scoreField(field, query, weight) {
+    const lowerField = field.toLowerCase();
+    const lowerQuery = query.toLowerCase();
+    if (!lowerField.includes(lowerQuery))
+        return 0;
+    if (lowerField === lowerQuery)
+        return weight * 4;
+    if (lowerField.startsWith(lowerQuery) || lowerField.endsWith(lowerQuery))
+        return weight * 3;
+    return weight * 2;
+}
+function sectionScore(document, language, sectionMarkdown, query, sectionTitle) {
+    const translation = document.translations[language];
+    const tokens = [...new Set(query.normalize('NFC').toLowerCase().split(/\s+/u))];
+    let score = 0;
+    for (const token of tokens) {
+        const tokenScore = scoreField(sectionTitle, token, 100) +
+            scoreField(translation.title, token, 30) +
+            scoreField(translation.summary, token, 20) +
+            scoreField((translation.terms ?? []).join(' '), token, 15) +
+            scoreField(sectionMarkdown, token, 10);
+        if (tokenScore === 0)
+            return 0;
+        score += tokenScore;
+    }
+    return score;
+}
+function sectionFromDocument(document, language, sectionId) {
+    const translation = document.translations[language];
+    if (sectionId === null) {
+        return { markdown: translation.markdown, source: translation.path, title: translation.title };
+    }
+    const section = translation.sections.find((entry) => entry.id === sectionId);
+    if (!section)
+        fail(`unknown section: ${sectionId}`);
+    return {
+        markdown: section.text,
+        source: sectionSource(translation.path, section.id),
+        title: section.title,
+    };
+}
+function parseSearchArgs(args) {
+    if (args.length === 0)
+        fail('missing search query');
+    const query = normalizeQuery(args[0]);
+    let language = 'en';
+    let limit = 5;
+    let json = false;
+    let seenLang = false;
+    let seenLimit = false;
+    let seenJson = false;
+    for (let index = 1; index < args.length; index += 1) {
+        const arg = args[index];
+        if (arg === '--lang') {
+            if (seenLang)
+                fail('duplicate --lang');
+            seenLang = true;
+            const value = args[index + 1];
+            if (value === undefined || value.startsWith('--'))
+                fail('missing --lang value');
+            language = languageFrom(value);
+            index += 1;
+            continue;
+        }
+        if (arg === '--limit') {
+            if (seenLimit)
+                fail('duplicate --limit');
+            seenLimit = true;
+            const value = args[index + 1];
+            if (value === undefined || value.startsWith('--'))
+                fail('missing --limit value');
+            if (!/^[1-9]\d*$/.test(value))
+                fail(`invalid limit: ${value}`);
+            const parsed = Number(value);
+            if (parsed < 1 || parsed > 50)
+                fail(`invalid limit: ${value}`);
+            limit = parsed;
+            index += 1;
+            continue;
+        }
+        if (arg === '--json') {
+            if (seenJson)
+                fail('duplicate --json');
+            seenJson = true;
+            json = true;
+            continue;
+        }
+        if (arg.startsWith('--'))
+            fail(`unknown search flag: ${arg}`);
+        fail(`unexpected search argument: ${arg}`);
+    }
+    return { query, language, limit, json };
+}
+function parseShowArgs(args) {
+    if (args.length === 0)
+        fail('missing document id');
+    const documentId = args[0];
+    if (!isDocumentId(documentId))
+        fail(`invalid document id: ${documentId}`);
+    let language = 'en';
+    let sectionId = null;
+    let json = false;
+    let seenLang = false;
+    let seenSection = false;
+    let seenJson = false;
+    for (let index = 1; index < args.length; index += 1) {
+        const arg = args[index];
+        if (arg === '--lang') {
+            if (seenLang)
+                fail('duplicate --lang');
+            seenLang = true;
+            const value = args[index + 1];
+            if (value === undefined || value.startsWith('--'))
+                fail('missing --lang value');
+            language = languageFrom(value);
+            index += 1;
+            continue;
+        }
+        if (arg === '--section') {
+            if (seenSection)
+                fail('duplicate --section');
+            seenSection = true;
+            const value = args[index + 1];
+            if (value === undefined || value.startsWith('--'))
+                fail('missing --section value');
+            if (!isSectionId(value))
+                fail(`invalid section id: ${value}`);
+            sectionId = value;
+            index += 1;
+            continue;
+        }
+        if (arg === '--json') {
+            if (seenJson)
+                fail('duplicate --json');
+            seenJson = true;
+            json = true;
+            continue;
+        }
+        if (arg.startsWith('--'))
+            fail(`unknown show flag: ${arg}`);
+        fail(`unexpected show argument: ${arg}`);
+    }
+    return { documentId, language, sectionId, json };
+}
+function parseTopicArgs(args) {
+    if (args.length === 0)
+        fail('missing docs topic');
+    const topic = args[0];
+    if (!topics.includes(topic))
+        fail(`unknown docs topic: ${topic}`);
+    let language = 'en';
+    let seenLang = false;
+    for (let index = 1; index < args.length; index += 1) {
+        const arg = args[index];
+        if (arg === '--lang') {
+            if (seenLang)
+                fail('duplicate --lang');
+            seenLang = true;
+            const value = args[index + 1];
+            if (value === undefined || value.startsWith('--'))
+                fail('missing --lang value');
+            language = languageFrom(value);
+            index += 1;
+            continue;
+        }
+        if (arg.startsWith('--'))
+            fail(`unknown docs flag: ${arg}`);
+        fail(`unexpected docs argument: ${arg}`);
+    }
+    return { topic, language };
+}
+function loadBundleRoot(docsRoot) {
+    if (!existsSync(join(docsRoot, 'catalog.json')) || !existsSync(join(docsRoot, 'index.json'))) {
+        fail('missing docs bundle');
+    }
+    return loadDocsBundle(docsRoot);
+}
+function searchBundle(bundleRoot, query, language, limit, version) {
+    const bundle = loadBundleRoot(bundleRoot);
+    const results = [];
+    for (const document of bundle.documents.values()) {
+        if (!document.bundled)
+            continue;
+        const translation = document.translations[language];
+        for (const section of translation.sections) {
+            const markdown = section.text;
+            const score = sectionScore(document, language, markdown, query, section.title);
+            if (score <= 0)
+                continue;
+            results.push({
+                documentId: document.id,
+                sectionId: section.id,
+                title: section.title,
+                excerpt: excerptFor(markdown, query),
+                source: sectionSource(translation.path, section.id),
+                command: shellCommand([
+                    'pdks',
+                    'docs',
+                    'show',
+                    document.id,
+                    '--lang',
+                    language,
+                    '--section',
+                    section.id,
+                ]),
+                score,
+            });
+        }
+    }
+    results.sort((left, right) => {
+        if (right.score !== left.score)
+            return right.score - left.score;
+        if (left.documentId !== right.documentId)
+            return left.documentId < right.documentId ? -1 : 1;
+        return left.sectionId < right.sectionId ? -1 : left.sectionId > right.sectionId ? 1 : 0;
+    });
+    return {
+        schemaVersion: 1,
+        packageVersion: version,
+        language,
+        query,
+        count: Math.min(results.length, limit),
+        results: results.slice(0, limit),
+    };
+}
+function renderSearchResultText(search) {
+    if (search.results.length === 0) {
+        return `0 results for ${search.query}\n[]\n`;
+    }
+    const lines = [
+        `${search.count} results for ${search.query} (${search.language})`,
+        ...search.results.map((result, index) => [
+            `${index + 1}. ${result.documentId}#${result.sectionId} ${result.title} [${result.score}]`,
+            `   ${result.excerpt}`,
+            `   ${result.source}`,
+            `   ${result.command}`,
+        ].join('\n')),
+    ];
+    return `${lines.join('\n\n')}\n`;
+}
+function renderTopic(bundleRoot, topic, language) {
+    const bundle = loadBundleRoot(bundleRoot);
+    const entry = bundle.topics[topic];
+    if (!entry)
+        fail(`unknown docs topic: ${topic}`);
+    const parts = [];
+    for (const reference of entry.references) {
+        const document = bundle.documents.get(reference.documentId);
+        if (!document)
+            fail(`unknown topic document: ${reference.documentId}`);
+        const section = sectionFromDocument(document, language, reference.sectionId ?? null);
+        parts.push(section.markdown);
+    }
+    parts.push(`See also: ${shellCommand(['pdks', 'docs', 'show', entry.seeAlso, '--lang', language])}`);
+    return `${parts.join('\n\n')}\n`;
+}
+/** Validate the source collection and replace the bundle, removing retired files. */
+export function buildDocs(spec) {
+    return buildDocsImpl(spec);
+}
+/** Answer a docs-only command without loading project configuration or the judge. */
+export function runDocs(spec) {
+    const args = spec.args;
+    if (args.length === 0)
+        return { text: rootHelp };
+    if (args.length === 1 && args[0] === '--help')
+        return { text: rootHelp };
+    if (args[0] === 'search') {
+        if (args.length === 2 && args[1] === '--help')
+            return { text: rootHelp };
+        const { query, language, limit, json } = parseSearchArgs(args.slice(1));
+        const search = searchBundle(spec.docsRoot, query, language, limit, spec.version);
+        return { text: json ? `${JSON.stringify(search)}\n` : renderSearchResultText(search) };
+    }
+    if (args[0] === 'show') {
+        if (args.length === 2 && args[1] === '--help')
+            return { text: rootHelp };
+        const { documentId, language, sectionId, json } = parseShowArgs(args.slice(1));
+        const bundle = loadBundleRoot(spec.docsRoot);
+        const document = bundle.documents.get(documentId);
+        if (!document)
+            fail(`unknown document: ${documentId}`);
+        const section = sectionFromDocument(document, language, sectionId);
+        if (json) {
+            const payload = {
+                schemaVersion: 1,
+                packageVersion: spec.version,
+                language,
+                documentId,
+                sectionId,
+                source: section.source,
+                markdown: section.markdown,
+            };
+            return { text: `${JSON.stringify(payload)}\n` };
+        }
+        return { text: section.markdown };
+    }
+    if (topics.includes(args[0])) {
+        const { topic, language } = parseTopicArgs(args);
+        return { text: renderTopic(spec.docsRoot, topic, language) };
+    }
+    fail(`unknown docs command: ${args[0]}`);
+}

package/dist/docs-markdown.d.ts

@@ -0,0 +1,32 @@
+import type { DocsSection } from './docs-types.ts';
+/** Compute a hex SHA-256 digest of the exact UTF-8 Markdown without normalizing whitespace. */
+export declare function hashMarkdown(markdown: string): string;
+/**
+ * Retrieve original Markdown by stable anchor ID, including the anchor and child headings.
+ *
+ * @param markdown - Complete document whose section anchors must be valid.
+ * @param sectionId - Anchor ID without a leading hash sign.
+ * @returns Unmodified section text up to the next same-level or higher-level heading.
+ * @throws If the section is absent or the document has missing or duplicate section anchors.
+ */
+export declare function extractSection(markdown: string, sectionId: string): string;
+/**
+ * Find anchored H2–H6 sections outside code fences, preserving their original Markdown.
+ *
+ * @param markdown - Complete source document to divide into retrievable sections.
+ * @param options - Require anchors for every H2–H6 heading, or omit unanchored headings.
+ * @returns Sections in document order, including nested content and their anchor lines.
+ * @throws If section IDs repeat or a required anchor is missing or not adjacent to its heading.
+ */
+export declare function parseSections(markdown: string, options: {
+    requireAnchors: boolean;
+}): DocsSection[];
+/**
+ * Look up a stable section ID after validating the document's section anchors.
+ *
+ * @param markdown - Complete source document, not just the target section.
+ * @param sectionId - Anchor ID without a leading hash sign.
+ * @returns The section and its source bounds, or undefined when the ID is absent.
+ * @throws If the document has missing or duplicate section anchors.
+ */
+export declare function headingMatch(markdown: string, sectionId: string): DocsSection | undefined;

package/dist/docs-markdown.js

@@ -0,0 +1,150 @@
+import { createHash } from 'node:crypto';
+const headingPattern = /^(#{1,6})\s+(.*)$/;
+const anchorPattern = /^<a id="([a-z0-9][a-z0-9-]*)"><\/a>$/;
+const sectionHeadingLevel = 2;
+function fenceMatch(line) {
+    const match = /^(`{3,}|~{3,})/.exec(line.trim());
+    if (!match)
+        return null;
+    return { marker: match[0][0], length: match[0].length };
+}
+function headingLevel(line) {
+    return headingPattern.exec(line)?.[1].length ?? 0;
+}
+function headingText(line) {
+    return headingPattern.exec(line)?.[2] ?? '';
+}
+function anchorId(line) {
+    return anchorPattern.exec(line.trim())?.[1] ?? null;
+}
+/** Compute a hex SHA-256 digest of the exact UTF-8 Markdown without normalizing whitespace. */
+export function hashMarkdown(markdown) {
+    return createHash('sha256').update(markdown, 'utf8').digest('hex');
+}
+/**
+ * Retrieve original Markdown by stable anchor ID, including the anchor and child headings.
+ *
+ * @param markdown - Complete document whose section anchors must be valid.
+ * @param sectionId - Anchor ID without a leading hash sign.
+ * @returns Unmodified section text up to the next same-level or higher-level heading.
+ * @throws If the section is absent or the document has missing or duplicate section anchors.
+ */
+export function extractSection(markdown, sectionId) {
+    const sections = parseSections(markdown, { requireAnchors: true });
+    const section = sections.find((entry) => entry.id === sectionId);
+    if (!section) {
+        throw new Error(`section not found: ${sectionId}`);
+    }
+    return section.text;
+}
+/**
+ * Find anchored H2–H6 sections outside code fences, preserving their original Markdown.
+ *
+ * @param markdown - Complete source document to divide into retrievable sections.
+ * @param options - Require anchors for every H2–H6 heading, or omit unanchored headings.
+ * @returns Sections in document order, including nested content and their anchor lines.
+ * @throws If section IDs repeat or a required anchor is missing or not adjacent to its heading.
+ */
+export function parseSections(markdown, options) {
+    const lines = markdown.split('\n');
+    const lineStarts = [0];
+    for (let index = 0; index < lines.length - 1; index += 1) {
+        lineStarts[index + 1] = lineStarts[index] + lines[index].length + 1;
+    }
+    const starts = [];
+    const topLevelBoundaries = [];
+    let fence;
+    for (let index = 0; index < lines.length; index += 1) {
+        const line = lines[index];
+        const match = fenceMatch(line);
+        if (match) {
+            if (fence === undefined) {
+                fence = match;
+            }
+            else if (fence.marker === match.marker && match.length >= fence.length) {
+                fence = undefined;
+            }
+            continue;
+        }
+        if (fence !== undefined) {
+            continue;
+        }
+        if (headingLevel(line) === 1) {
+            let previous = index - 1;
+            while (previous >= 0 && lines[previous].trim() === '')
+                previous -= 1;
+            topLevelBoundaries.push(previous >= 0 && anchorId(lines[previous]) ? previous : index);
+        }
+        if (headingLevel(line) < sectionHeadingLevel) {
+            continue;
+        }
+        let anchorLine = index - 1;
+        while (anchorLine >= 0 && lines[anchorLine].trim() === '') {
+            anchorLine -= 1;
+        }
+        if (anchorLine < 0) {
+            if (options.requireAnchors) {
+                throw new Error(`missing anchor for heading: ${line}`);
+            }
+            continue;
+        }
+        const id = anchorId(lines[anchorLine]);
+        if (!id) {
+            if (options.requireAnchors) {
+                throw new Error(`missing anchor for heading: ${line}`);
+            }
+            continue;
+        }
+        const blankSpan = lines.slice(anchorLine + 1, index).every((entry) => entry.trim() === '');
+        if (!blankSpan) {
+            if (options.requireAnchors) {
+                throw new Error(`anchor not adjacent to heading: ${line}`);
+            }
+            continue;
+        }
+        starts.push({
+            id,
+            title: headingText(line),
+            level: headingLevel(line),
+            startLine: anchorLine,
+            startOffset: lineStarts[anchorLine],
+        });
+    }
+    const sections = starts.map((start, index) => {
+        let endLine = topLevelBoundaries.find((line) => line > start.startLine) ?? lines.length;
+        for (let candidate = index + 1; candidate < starts.length; candidate += 1) {
+            if (starts[candidate].level <= start.level) {
+                endLine = Math.min(endLine, starts[candidate].startLine);
+                break;
+            }
+        }
+        const endOffset = endLine >= lines.length ? markdown.length : lineStarts[endLine];
+        return {
+            id: start.id,
+            title: start.title,
+            level: start.level,
+            startLine: start.startLine,
+            endLine,
+            text: markdown.slice(start.startOffset, endOffset),
+        };
+    });
+    const ids = new Set();
+    for (const section of sections) {
+        if (ids.has(section.id)) {
+            throw new Error(`duplicate section id: ${section.id}`);
+        }
+        ids.add(section.id);
+    }
+    return sections;
+}
+/**
+ * Look up a stable section ID after validating the document's section anchors.
+ *
+ * @param markdown - Complete source document, not just the target section.
+ * @param sectionId - Anchor ID without a leading hash sign.
+ * @returns The section and its source bounds, or undefined when the ID is absent.
+ * @throws If the document has missing or duplicate section anchors.
+ */
+export function headingMatch(markdown, sectionId) {
+    return parseSections(markdown, { requireAnchors: true }).find((section) => section.id === sectionId);
+}

package/dist/docs-query.d.ts

@@ -1,46 +1,17 @@
-/**
- * `queryDocs` — the offline documentation query.
- *
- * The bundled English guides, answered from the installed version. An AI partner that
- * searches the web gets whatever release the internet indexed; this returns the document
- * that shipped with the code doing the judging, with no network at all.
- *
- * The domain is the five topics below and nothing else. An unknown topic throws instead of
- * resolving to something near it: an answer to a question we never mapped is
- * indistinguishable from a real one by the time it reaches a reader.
- *
- * Every failure throws so the bin can leave stdout at zero bytes and exit 2. Text written
- * halfway is read as the document and quoted as the document — the same direction the
- * judging surface fails in, for the same reason.
- */
-/** The finite query domain — the topic list `pdks docs` prints with no argument. */
-export declare const TOPICS: readonly ['install', 'config', 'discipline', 'covenant', 'witness'];
-/**
- * The body of one section of `markdown`: from the line equal to `heading` up to just before
- * the next heading of the same or a higher level, returned verbatim.
- *
- * `heading` is matched by exact string equality. A document that renames its heading kills
- * the query here rather than letting a normalizing matcher hand back a neighbouring section
- * with full confidence.
- *
- * Both scans — for the start and for the boundary — run outside code fences. `#` lines
- * inside a fence are content: the guides really carry them, and a fence-blind scanner cuts
- * the answer at one of those lines while still looking like a success.
- */
-export declare function extractSection(markdown: string, heading: string): string;
-/** `queryDocs` input — the bundle to read from, and which topic to answer. */
+export { DOCS_TOPICS as TOPICS } from './docs-types.ts';
+/** Inputs for the original five-topic query interface. */
 export type QueryDocsSpec = {
-    /** Root of the bundled documents (`dist/docs`), the only tree read here. */
     docsRoot: string;
-    /** ABSENT lists the topics; anything not in {@link TOPICS} throws, empty string included. */
     topic?: string;
 };
-/**
- * Answer one documentation query.
- *
- * With no topic the result is the listing — how an AI discovers what it may ask at all.
- * With one, it is the mapped section body followed by the bundled reference to read next.
- */
-export declare function queryDocs(spec: QueryDocsSpec): {
+/** Complete topic output, including the command for further reading. */
+export type QueryDocsOutcome = {
     text: string;
 };
+/** Answer a legacy topic using the same catalog as search and show. */
+export declare function queryDocs(spec: QueryDocsSpec): QueryDocsOutcome;
+/**
+ * Extract a section by its exact heading, retaining the original internal helper's contract.
+ * Topic retrieval uses stable IDs instead; this helper remains for existing internal callers.
+ */
+export declare function extractSection(markdown: string, heading: string): string;