@mortice/mapwright 0.8.0

package/dist/extractors/docTags.js

@@ -0,0 +1,106 @@
+const VALID_TAGS = new Set([
+    "catalogue",
+    "capability",
+    "publicApi",
+    "internalApi",
+    "stability",
+    "intendedUse",
+    "inputs",
+    "returns",
+    "contract",
+    "errors",
+    "example",
+    "tests",
+    "coversCapability",
+    "coversSymbol",
+    "coversPublicApi",
+    "editable",
+    "editPolicy"
+]);
+const VALID_STABILITY = ["stable", "experimental", "deprecated", "internal", "test-only", "unknown"];
+const VALID_EDITABLE = ["none", "allowed", "restricted", "maintainer-only", "unknown"];
+const VALID_VISIBILITY = [
+    "published",
+    "supported_internal",
+    "private",
+    "test_only",
+    "experimental",
+    "deprecated",
+    "ignored",
+    "unknown"
+];
+export function parseDocTags(text, filePath) {
+    const lines = text.split(/\r?\n/);
+    const tags = [];
+    const diagnostics = [];
+    const summaryLines = [];
+    for (const rawLine of lines) {
+        const line = rawLine.replace(/^\s*\*\s?/, "").trim();
+        if (!line)
+            continue;
+        const tagMatch = line.match(/^@([A-Za-z][A-Za-z0-9]*)\s*(.*)$/);
+        if (tagMatch) {
+            const [, tag, valueRaw] = tagMatch;
+            const value = valueRaw.trim();
+            if (!VALID_TAGS.has(tag)) {
+                diagnostics.push({
+                    id: `diag:${filePath}:invalid_catalogue_tag:${tag}`,
+                    severity: "warning",
+                    category: "documentation",
+                    code: "invalid_catalogue_tag",
+                    message: `Unknown documentation tag @${tag}.`,
+                    filePath,
+                    provenance: { source: "doc-tags" }
+                });
+                continue;
+            }
+            if (tag === "stability" && value && !VALID_STABILITY.includes(value)) {
+                diagnostics.push({
+                    id: `diag:${filePath}:invalid_stability_value:${value}`,
+                    severity: "warning",
+                    category: "documentation",
+                    code: "invalid_stability_value",
+                    message: `Invalid @stability value: ${value}.`,
+                    filePath,
+                    provenance: { source: "doc-tags" }
+                });
+            }
+            if (tag === "editable" && value && !VALID_EDITABLE.includes(value)) {
+                diagnostics.push({
+                    id: `diag:${filePath}:invalid_editability_value:${value}`,
+                    severity: "warning",
+                    category: "documentation",
+                    code: "invalid_editability_value",
+                    message: `Invalid @editable value: ${value}.`,
+                    filePath,
+                    provenance: { source: "doc-tags" }
+                });
+            }
+            if (tag === "catalogue" && value && !VALID_VISIBILITY.includes(value) && !["public-api", "internal-api", "test", "example", "file", "package", "capability", "ignore"].includes(value)) {
+                diagnostics.push({
+                    id: `diag:${filePath}:invalid_catalogue_tag:catalogue`,
+                    severity: "warning",
+                    category: "documentation",
+                    code: "invalid_catalogue_tag",
+                    message: `Potentially invalid @catalogue value: ${value}.`,
+                    filePath,
+                    provenance: { source: "doc-tags" }
+                });
+            }
+            tags.push({ tag, value });
+            continue;
+        }
+        summaryLines.push(line);
+    }
+    return {
+        summary: summaryLines.join(" ").trim(),
+        tags,
+        diagnostics
+    };
+}
+export function firstTag(tags, name) {
+    return tags.find((t) => t.tag === name)?.value;
+}
+export function manyTags(tags, name) {
+    return tags.filter((t) => t.tag === name).map((t) => t.value).filter(Boolean);
+}

package/dist/extractors/generic.d.ts

@@ -0,0 +1,5 @@
+import type { FileRecord } from "../catalogue/schema.js";
+export interface GenericExtractionResult {
+    symbols: never[];
+}
+export declare function extractGeneric(_file: FileRecord): GenericExtractionResult;

package/dist/extractors/generic.js

@@ -0,0 +1,3 @@
+export function extractGeneric(_file) {
+    return { symbols: [] };
+}

package/dist/extractors/javascript.d.ts

@@ -0,0 +1,3 @@
+import type { FileRecord, PackageRecord } from "../catalogue/schema.js";
+import { type TsExtractionResult } from "./typescript.js";
+export declare function extractJavaScriptSymbols(workspaceRoot: string, file: FileRecord, packageRecord?: PackageRecord): TsExtractionResult;

package/dist/extractors/javascript.js

@@ -0,0 +1,4 @@
+import { extractTypeScriptSymbols } from "./typescript.js";
+export function extractJavaScriptSymbols(workspaceRoot, file, packageRecord) {
+    return extractTypeScriptSymbols(workspaceRoot, file, packageRecord);
+}

package/dist/extractors/markdown.d.ts

@@ -0,0 +1,7 @@
+import type { CapabilityRecord, ExampleRecord, PackageRecord } from "../catalogue/schema.js";
+export interface MarkdownCatalogueResult {
+    packages: PackageRecord[];
+    capabilities: CapabilityRecord[];
+    examples: ExampleRecord[];
+}
+export declare function extractCatalogueMarkdown(workspaceRoot: string, filePath: string): MarkdownCatalogueResult;

package/dist/extractors/markdown.js

@@ -0,0 +1,269 @@
+import path from "node:path";
+import { readFileSync } from "node:fs";
+import { buildDeterministicExampleId, normalizeExamplePath } from "../catalogue/examples.js";
+import { packageIdentityId } from "../catalogue/identity.js";
+export function extractCatalogueMarkdown(workspaceRoot, filePath) {
+    const absolute = path.resolve(workspaceRoot, filePath);
+    const text = readFileSync(absolute, "utf8");
+    const lines = text.split(/\r?\n/);
+    const packages = [];
+    const capabilities = [];
+    const examples = [];
+    const sectionRanges = splitSections(lines);
+    const normalizedPath = path.dirname(filePath).replaceAll(path.sep, "/") || ".";
+    const packageSection = sectionRanges.find((section) => section.title.toLowerCase() === "package");
+    const fallbackPackageName = readInlineField(lines, "Name:");
+    const packageName = readSectionField(lines, packageSection, "Name") ?? fallbackPackageName;
+    const packageId = packageName
+        ? packageIdentityId({ ecosystem: "unknown", name: normalizeMarkdownValue(packageName), root: normalizedPath })
+        : undefined;
+    if (packageName) {
+        const purpose = readSectionField(lines, packageSection, "Purpose");
+        const summary = readSectionField(lines, packageSection, "Summary") ?? purpose;
+        const stability = readSectionField(lines, packageSection, "Stability") ?? "unknown";
+        packages.push({
+            id: packageId,
+            name: normalizeMarkdownValue(packageName),
+            path: normalizedPath,
+            summary,
+            capabilities: [],
+            publicApis: [],
+            tests: [],
+            stability: isStability(stability) ? stability : "unknown",
+            provenance: { source: "catalogue-md", locations: [filePath] }
+        });
+    }
+    for (const section of sectionRanges) {
+        const capabilityHeading = section.title.match(/^Capability:\s+(.+)$/i);
+        if (!capabilityHeading) {
+            continue;
+        }
+        const rawCapability = normalizeMarkdownValue(capabilityHeading[1]);
+        const capabilityName = normalizeMarkdownValue(readSectionField(lines, section, "Name") ?? rawCapability);
+        const summary = readSectionField(lines, section, "Summary");
+        const stability = readSectionField(lines, section, "Stability") ?? "unknown";
+        const intendedUse = readSectionField(lines, section, "Intended use");
+        const publicApiRefs = readSectionBullets(lines, section, "Public APIs");
+        const capabilityTests = readSectionBullets(lines, section, "Tests");
+        const contracts = readSectionBullets(lines, section, "Contracts");
+        const limitations = readSectionBullets(lines, section, "Limitations");
+        const capabilityId = normalizeCapabilityId(rawCapability);
+        const capabilityExamples = readSectionBullets(lines, section, "Examples");
+        const exampleIds = [];
+        for (const reference of capabilityExamples) {
+            const parsedRef = parseExampleReference(reference);
+            const exampleId = buildDeterministicExampleId(parsedRef.filePath, parsedRef.anchor, reference);
+            exampleIds.push(exampleId);
+            examples.push({
+                id: exampleId,
+                title: parsedRef.title,
+                filePath: parsedRef.filePath,
+                anchor: parsedRef.anchor,
+                capabilityIds: [parsedRef.capabilityId ? normalizeCapabilityId(parsedRef.capabilityId) : capabilityId],
+                // Path-only bullets link the capability; public API linkage comes from explicit
+                // public-api: tokens and/or file-level @coversPublicApi annotations.
+                publicApiIds: parsedRef.publicApiRefs.map((ref) => normalizeMarkdownValue(ref)),
+                symbolIds: [],
+                summary: undefined,
+                provenance: {
+                    source: "catalogue-md",
+                    locations: [filePath],
+                    warnings: parsedRef.warnings.length > 0 ? parsedRef.warnings : undefined
+                }
+            });
+        }
+        capabilities.push({
+            id: capabilityId,
+            name: capabilityName,
+            summary,
+            keywords: rawCapability.split(/[.\-]/).filter(Boolean),
+            status: "available",
+            stability: isStability(stability) ? stability : "unknown",
+            intendedUse,
+            publicApis: publicApiRefs,
+            symbols: [],
+            files: [filePath],
+            packages: packageId ? [packageId] : [],
+            examples: exampleIds,
+            tests: capabilityTests,
+            contracts,
+            limitations,
+            provenance: { source: "catalogue-md", locations: [filePath] }
+        });
+    }
+    return {
+        packages: packages.sort((a, b) => a.id.localeCompare(b.id)),
+        capabilities: capabilities.sort((a, b) => a.id.localeCompare(b.id)),
+        examples: examples.sort((a, b) => a.id.localeCompare(b.id))
+    };
+}
+function readInlineField(lines, label) {
+    const labelLower = label.toLowerCase();
+    for (const line of lines) {
+        const trimmed = line.trimStart();
+        if (!trimmed.toLowerCase().startsWith(labelLower)) {
+            continue;
+        }
+        const inline = trimmed.slice(label.length);
+        return normalizeMarkdownValue(inline.trim());
+    }
+    return undefined;
+}
+function splitSections(lines) {
+    const sections = [];
+    for (let i = 0; i < lines.length; i += 1) {
+        const match = lines[i]?.match(/^##\s+(.+)$/);
+        if (!match) {
+            continue;
+        }
+        sections.push({ title: match[1].trim(), start: i + 1, end: lines.length - 1 });
+    }
+    for (let i = 0; i < sections.length; i += 1) {
+        const next = sections[i + 1];
+        if (next) {
+            sections[i].end = next.start - 2;
+        }
+    }
+    return sections;
+}
+function readSectionField(lines, section, label) {
+    if (!section) {
+        return undefined;
+    }
+    const labelPattern = new RegExp(`^${escapeForRegex(label)}\\s*:\\s*(.*)$`, "i");
+    for (let i = section.start; i <= section.end; i += 1) {
+        const line = lines[i] ?? "";
+        const match = line.trim().match(labelPattern);
+        if (!match) {
+            continue;
+        }
+        const inline = normalizeMarkdownValue(match[1] ?? "");
+        if (inline) {
+            return inline;
+        }
+        const out = [];
+        for (let j = i + 1; j <= section.end; j += 1) {
+            const raw = lines[j] ?? "";
+            const trimmed = raw.trim();
+            if (!trimmed) {
+                if (out.length > 0) {
+                    break;
+                }
+                continue;
+            }
+            if (/^[A-Za-z][A-Za-z\s]+\s*:/.test(trimmed)) {
+                break;
+            }
+            if (/^-\s+/.test(trimmed)) {
+                break;
+            }
+            out.push(normalizeMarkdownValue(trimmed));
+        }
+        return out.length > 0 ? out.join(" ").trim() : undefined;
+    }
+    return undefined;
+}
+function readSectionBullets(lines, section, label) {
+    const labelPattern = new RegExp(`^${escapeForRegex(label)}\\s*:\\s*$`, "i");
+    const out = [];
+    for (let i = section.start; i <= section.end; i += 1) {
+        const line = lines[i] ?? "";
+        if (!labelPattern.test(line.trim())) {
+            continue;
+        }
+        for (let j = i + 1; j <= section.end; j += 1) {
+            const item = lines[j] ?? "";
+            const trimmed = item.trim();
+            if (!trimmed) {
+                if (out.length > 0) {
+                    break;
+                }
+                continue;
+            }
+            const bullet = trimmed.match(/^-\s+(.+)$/);
+            if (!bullet) {
+                break;
+            }
+            out.push(normalizeMarkdownValue(bullet[1]));
+        }
+        break;
+    }
+    return out;
+}
+function normalizeCapabilityId(value) {
+    const normalized = value.replace(/^capability:/i, "").trim();
+    return `capability:${normalized}`;
+}
+function normalizeMarkdownValue(value) {
+    return value.replace(/`/g, "").trim();
+}
+function parseExampleReference(reference) {
+    const normalized = normalizeMarkdownValue(reference);
+    if (!normalized) {
+        return { publicApiRefs: [], warnings: ["example_reference_empty"] };
+    }
+    const metadataParts = normalized.split("|").map((part) => part.trim()).filter(Boolean);
+    let referencePart;
+    let capabilityId;
+    const publicApiRefs = [];
+    const warnings = [];
+    for (const part of metadataParts) {
+        const lower = part.toLowerCase();
+        if (lower.startsWith("capability:")) {
+            const value = part.slice("capability:".length).trim();
+            if (value) {
+                capabilityId = value;
+            }
+            else {
+                warnings.push("example_metadata_capability_empty");
+            }
+            continue;
+        }
+        if (lower.startsWith("public-api:")) {
+            const value = part.slice("public-api:".length).trim();
+            if (value) {
+                publicApiRefs.push(value);
+            }
+            else {
+                warnings.push("example_metadata_public_api_empty");
+            }
+            continue;
+        }
+        if (/^[a-z0-9_-]+:/i.test(part) && metadataParts.length > 1) {
+            warnings.push("example_metadata_unknown_token");
+            continue;
+        }
+        referencePart = part;
+    }
+    if (!referencePart && metadataParts.length === 1) {
+        referencePart = metadataParts[0];
+    }
+    if (!referencePart) {
+        warnings.push("example_missing_file_path");
+        return { capabilityId, publicApiRefs: [...new Set(publicApiRefs)].sort(), warnings };
+    }
+    const [rawPath, rawAnchor] = referencePart.split("#", 2);
+    const filePathCandidate = normalizeExamplePath(rawPath?.trim() || undefined);
+    const filePathLooksMetadata = typeof filePathCandidate === "string"
+        && (filePathCandidate.toLowerCase().startsWith("capability:") || filePathCandidate.toLowerCase().startsWith("public-api:"));
+    const filePath = filePathLooksMetadata ? undefined : filePathCandidate;
+    if (!filePath) {
+        warnings.push("example_missing_file_path");
+    }
+    const anchor = rawAnchor?.trim() || undefined;
+    const title = anchor ? anchor.replace(/[-_]/g, " ") : filePath ? path.basename(filePath) : undefined;
+    return {
+        filePath,
+        anchor,
+        title,
+        capabilityId,
+        publicApiRefs: [...new Set(publicApiRefs)].sort(),
+        warnings: [...new Set(warnings)].sort()
+    };
+}
+function escapeForRegex(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+function isStability(value) {
+    return ["stable", "experimental", "deprecated", "internal", "test-only", "unknown"].includes(value);
+}

package/dist/extractors/python.d.ts

@@ -0,0 +1,7 @@
+import type { DiagnosticRecord, FileRecord, PackageRecord, RelationshipRecord, SymbolRecord } from "../catalogue/schema.js";
+export interface PythonExtractionResult {
+    symbols: SymbolRecord[];
+    relationships: RelationshipRecord[];
+    diagnostics: DiagnosticRecord[];
+}
+export declare function extractPythonSymbols(workspaceRoot: string, file: FileRecord, packageRecord?: PackageRecord): PythonExtractionResult;