mdkg 0.0.1 → 0.0.2

package/dist/commands/validate.js

@@ -0,0 +1,229 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runValidateCommand = runValidateCommand;
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const config_1 = require("../core/config");
+const template_schema_1 = require("../graph/template_schema");
+const node_1 = require("../graph/node");
+const workspace_files_1 = require("../graph/workspace_files");
+const validate_graph_1 = require("../graph/validate_graph");
+const errors_1 = require("../util/errors");
+const RECOMMENDED_HEADINGS = {
+    task: [
+        "Overview",
+        "Acceptance Criteria",
+        "Files Affected",
+        "Implementation Notes",
+        "Test Plan",
+        "Links / Artifacts",
+    ],
+    bug: [
+        "Overview",
+        "Reproduction Steps",
+        "Expected vs Actual",
+        "Suspected Cause",
+        "Fix Plan",
+        "Test Plan",
+        "Links / Artifacts",
+    ],
+    feat: ["Overview", "Acceptance Criteria", "Notes"],
+    epic: ["Goal", "Scope", "Milestones", "Out of Scope", "Risks", "Links / Artifacts"],
+    checkpoint: [
+        "Summary",
+        "Scope Covered",
+        "Decisions Captured",
+        "Implementation Summary",
+        "Verification / Testing",
+        "Known Issues / Follow-ups",
+        "Links / Artifacts",
+    ],
+    prd: [
+        "Problem",
+        "Goals",
+        "Non-goals",
+        "Requirements",
+        "Acceptance Criteria",
+        "Metrics / Success",
+        "Risks",
+        "Open Questions",
+    ],
+    edd: [
+        "Overview",
+        "Architecture",
+        "Data model",
+        "APIs / interfaces",
+        "Failure modes",
+        "Observability",
+        "Security / privacy",
+        "Testing strategy",
+        "Rollout plan",
+    ],
+    dec: ["Context", "Decision", "Alternatives considered", "Consequences", "Links / references"],
+};
+function normalizeHeading(value) {
+    return value.trim().toLowerCase();
+}
+function extractHeadings(body) {
+    const headings = new Set();
+    const lines = body.split(/\r?\n/);
+    for (const line of lines) {
+        const match = /^#+\s+(.*)$/.exec(line);
+        if (!match) {
+            continue;
+        }
+        headings.add(normalizeHeading(match[1] ?? ""));
+    }
+    return headings;
+}
+function isCoreListFile(filePath) {
+    return path_1.default.basename(filePath) === "core.md" && path_1.default.basename(path_1.default.dirname(filePath)) === "core";
+}
+function normalizeEdgeTarget(value, ws) {
+    if (value.includes(":")) {
+        return value;
+    }
+    return `${ws}:${value}`;
+}
+function normalizeEdges(edges, ws) {
+    return {
+        epic: edges.epic ? normalizeEdgeTarget(edges.epic, ws) : undefined,
+        parent: edges.parent ? normalizeEdgeTarget(edges.parent, ws) : undefined,
+        prev: edges.prev ? normalizeEdgeTarget(edges.prev, ws) : undefined,
+        next: edges.next ? normalizeEdgeTarget(edges.next, ws) : undefined,
+        relates: edges.relates.map((value) => normalizeEdgeTarget(value, ws)),
+        blocked_by: edges.blocked_by.map((value) => normalizeEdgeTarget(value, ws)),
+        blocks: edges.blocks.map((value) => normalizeEdgeTarget(value, ws)),
+    };
+}
+function buildIndexNode(root, ws, filePath, node) {
+    return {
+        id: node.id,
+        qid: `${ws}:${node.id}`,
+        ws,
+        type: node.type,
+        title: node.title,
+        status: node.status,
+        priority: node.priority,
+        created: node.created,
+        updated: node.updated,
+        tags: node.tags,
+        owners: node.owners,
+        links: node.links,
+        artifacts: node.artifacts,
+        refs: node.refs,
+        aliases: node.aliases,
+        path: path_1.default.relative(root, filePath),
+        edges: normalizeEdges(node.edges, ws),
+    };
+}
+function buildWorkspaceMap(config) {
+    const workspaces = {};
+    for (const alias of Object.keys(config.workspaces).sort()) {
+        const entry = config.workspaces[alias];
+        workspaces[alias] = { path: entry.path, enabled: entry.enabled };
+    }
+    return workspaces;
+}
+function runValidateCommand(options) {
+    const config = (0, config_1.loadConfig)(options.root);
+    const templateSchemas = (0, template_schema_1.loadTemplateSchemas)(options.root, config, node_1.ALLOWED_TYPES);
+    const filesByAlias = (0, workspace_files_1.listWorkspaceDocFilesByAlias)(options.root, config);
+    const errors = [];
+    const warnings = [];
+    const nodes = {};
+    const idsByWorkspace = {};
+    for (const [alias, files] of Object.entries(filesByAlias)) {
+        idsByWorkspace[alias] = new Map();
+        for (const filePath of files) {
+            if (isCoreListFile(filePath)) {
+                continue;
+            }
+            let content = "";
+            try {
+                content = fs_1.default.readFileSync(filePath, "utf8");
+            }
+            catch (err) {
+                const message = err instanceof Error ? err.message : "unknown error";
+                errors.push(`${filePath}: failed to read file: ${message}`);
+                continue;
+            }
+            try {
+                const node = (0, node_1.parseNode)(content, filePath, {
+                    workStatusEnum: config.work.status_enum,
+                    priorityMin: config.work.priority_min,
+                    priorityMax: config.work.priority_max,
+                    templateSchemas,
+                });
+                if (idsByWorkspace[alias].has(node.id)) {
+                    const firstPath = idsByWorkspace[alias].get(node.id);
+                    errors.push(`${filePath}: duplicate id ${node.id} in workspace ${alias} (also in ${firstPath})`);
+                    continue;
+                }
+                idsByWorkspace[alias].set(node.id, filePath);
+                const qid = `${alias}:${node.id}`;
+                nodes[qid] = buildIndexNode(options.root, alias, filePath, node);
+                const recommended = RECOMMENDED_HEADINGS[node.type];
+                if (recommended) {
+                    const headings = extractHeadings(node.body);
+                    for (const heading of recommended) {
+                        if (!headings.has(normalizeHeading(heading))) {
+                            warnings.push(`${qid}: missing recommended heading "${heading}"`);
+                        }
+                    }
+                }
+            }
+            catch (err) {
+                const message = err instanceof Error ? err.message : "unknown error";
+                errors.push(message);
+            }
+        }
+    }
+    const index = {
+        meta: {
+            tool: config.tool,
+            schema_version: config.schema_version,
+            generated_at: new Date().toISOString(),
+            root: options.root,
+            workspaces: Object.keys(filesByAlias).sort(),
+        },
+        workspaces: buildWorkspaceMap(config),
+        nodes,
+        reverse_edges: {},
+    };
+    const graphErrors = (0, validate_graph_1.collectGraphErrors)(index, { allowMissing: false });
+    errors.push(...graphErrors);
+    const reportLines = [
+        ...warnings.map((warning) => `warning: ${warning}`),
+        ...errors,
+    ];
+    let outPath = undefined;
+    if (options.out) {
+        outPath = path_1.default.resolve(options.root, options.out);
+        fs_1.default.mkdirSync(path_1.default.dirname(outPath), { recursive: true });
+        fs_1.default.writeFileSync(outPath, reportLines.join("\n"), "utf8");
+    }
+    if (!options.quiet) {
+        for (const warning of warnings) {
+            console.error(`warning: ${warning}`);
+        }
+    }
+    if (errors.length > 0) {
+        if (outPath) {
+            console.error(`validation failed: ${errors.length} error(s). details written to ${outPath}`);
+        }
+        else {
+            for (const error of errors) {
+                console.error(error);
+            }
+        }
+        throw new errors_1.ValidationError(`validation failed with ${errors.length} error(s)`);
+    }
+    if (outPath) {
+        console.log(`validation report written: ${outPath}`);
+    }
+    console.log("validation ok");
+}

package/dist/commands/workspace.js

@@ -0,0 +1,101 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runWorkspaceListCommand = runWorkspaceListCommand;
+exports.runWorkspaceAddCommand = runWorkspaceAddCommand;
+exports.runWorkspaceRemoveCommand = runWorkspaceRemoveCommand;
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const config_1 = require("../core/config");
+const errors_1 = require("../util/errors");
+const ALIAS_RE = /^[a-z][a-z0-9_]*$/;
+function readRawConfig(root) {
+    const configPath = path_1.default.join(root, ".mdkg", "config.json");
+    if (!fs_1.default.existsSync(configPath)) {
+        throw new errors_1.NotFoundError(`config not found at ${configPath}`);
+    }
+    let raw;
+    try {
+        raw = JSON.parse(fs_1.default.readFileSync(configPath, "utf8"));
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : "unknown error";
+        throw new errors_1.UsageError(`failed to read config: ${message}`);
+    }
+    if (typeof raw !== "object" || raw === null) {
+        throw new errors_1.UsageError("config must be a JSON object");
+    }
+    return { path: configPath, raw: raw };
+}
+function writeRawConfig(configPath, raw) {
+    fs_1.default.writeFileSync(configPath, JSON.stringify(raw, null, 2), "utf8");
+}
+function normalizeAlias(alias) {
+    const normalized = alias.toLowerCase();
+    if (normalized === "all") {
+        throw new errors_1.UsageError("workspace alias cannot be 'all'");
+    }
+    if (!ALIAS_RE.test(normalized)) {
+        throw new errors_1.UsageError("workspace alias must be lowercase and use [a-z0-9_]");
+    }
+    return normalized;
+}
+function runWorkspaceListCommand(options) {
+    const config = (0, config_1.loadConfig)(options.root);
+    const aliases = Object.keys(config.workspaces).sort();
+    if (aliases.length === 0) {
+        console.log("no workspaces registered");
+        return;
+    }
+    for (const alias of aliases) {
+        const ws = config.workspaces[alias];
+        const status = ws.enabled ? "enabled" : "disabled";
+        console.log(`${alias} | ${status} | ${ws.path} | ${ws.mdkg_dir}`);
+    }
+}
+function runWorkspaceAddCommand(options) {
+    const alias = normalizeAlias(options.alias);
+    const workspacePath = options.workspacePath.trim();
+    if (!workspacePath) {
+        throw new errors_1.UsageError("workspace path cannot be empty");
+    }
+    const mdkgDir = options.mdkgDir?.trim() || ".mdkg";
+    const { path: configPath, raw } = readRawConfig(options.root);
+    const workspacesRaw = raw.workspaces;
+    if (typeof workspacesRaw !== "object" || workspacesRaw === null) {
+        throw new errors_1.UsageError("config.workspaces must be an object");
+    }
+    const workspaces = workspacesRaw;
+    if (workspaces[alias]) {
+        throw new errors_1.UsageError(`workspace already exists: ${alias}`);
+    }
+    workspaces[alias] = { path: workspacePath, enabled: true, mdkg_dir: mdkgDir };
+    raw.workspaces = workspaces;
+    writeRawConfig(configPath, raw);
+    const wsRoot = path_1.default.resolve(options.root, workspacePath, mdkgDir);
+    fs_1.default.mkdirSync(path_1.default.join(wsRoot, "core"), { recursive: true });
+    fs_1.default.mkdirSync(path_1.default.join(wsRoot, "design"), { recursive: true });
+    fs_1.default.mkdirSync(path_1.default.join(wsRoot, "work"), { recursive: true });
+    console.log(`workspace added: ${alias} (${workspacePath})`);
+}
+function runWorkspaceRemoveCommand(options) {
+    const alias = normalizeAlias(options.alias);
+    if (alias === "root") {
+        throw new errors_1.UsageError("cannot remove root workspace");
+    }
+    const { path: configPath, raw } = readRawConfig(options.root);
+    const workspacesRaw = raw.workspaces;
+    if (typeof workspacesRaw !== "object" || workspacesRaw === null) {
+        throw new errors_1.UsageError("config.workspaces must be an object");
+    }
+    const workspaces = workspacesRaw;
+    if (!workspaces[alias]) {
+        throw new errors_1.NotFoundError(`workspace not found: ${alias}`);
+    }
+    delete workspaces[alias];
+    raw.workspaces = workspaces;
+    writeRawConfig(configPath, raw);
+    console.log(`workspace removed: ${alias}`);
+}

package/dist/core/config.js

@@ -0,0 +1,162 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.loadConfig = loadConfig;
+const fs_1 = __importDefault(require("fs"));
+const paths_1 = require("./paths");
+const migrate_1 = require("./migrate");
+function isObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function requireString(value, path, errors) {
+    if (typeof value !== "string") {
+        errors.push(`${path} must be a string`);
+        return undefined;
+    }
+    return value;
+}
+function requireBoolean(value, path, errors) {
+    if (typeof value !== "boolean") {
+        errors.push(`${path} must be a boolean`);
+        return undefined;
+    }
+    return value;
+}
+function requireNumber(value, path, errors) {
+    if (typeof value !== "number" || Number.isNaN(value)) {
+        errors.push(`${path} must be a number`);
+        return undefined;
+    }
+    return value;
+}
+function requireStringArray(value, path, errors) {
+    if (!Array.isArray(value)) {
+        errors.push(`${path} must be an array of strings`);
+        return undefined;
+    }
+    const items = [];
+    for (let i = 0; i < value.length; i += 1) {
+        if (typeof value[i] !== "string") {
+            errors.push(`${path}[${i}] must be a string`);
+            continue;
+        }
+        items.push(value[i]);
+    }
+    return items;
+}
+function requireObject(value, path, errors) {
+    if (!isObject(value)) {
+        errors.push(`${path} must be an object`);
+        return undefined;
+    }
+    return value;
+}
+function validateConfigSchema(raw) {
+    const errors = [];
+    if (!isObject(raw)) {
+        throw new Error("config must be a JSON object");
+    }
+    const schema_version = requireNumber(raw.schema_version, "schema_version", errors);
+    const tool = requireString(raw.tool, "tool", errors);
+    const root_required = requireBoolean(raw.root_required, "root_required", errors);
+    const indexRaw = requireObject(raw.index, "index", errors);
+    const packRaw = requireObject(raw.pack, "pack", errors);
+    const templatesRaw = requireObject(raw.templates, "templates", errors);
+    const workRaw = requireObject(raw.work, "work", errors);
+    const workspacesRaw = requireObject(raw.workspaces, "workspaces", errors);
+    const index = indexRaw
+        ? {
+            auto_reindex: requireBoolean(indexRaw.auto_reindex, "index.auto_reindex", errors),
+            tolerant: requireBoolean(indexRaw.tolerant, "index.tolerant", errors),
+            global_index_path: requireString(indexRaw.global_index_path, "index.global_index_path", errors),
+        }
+        : undefined;
+    const packLimitsRaw = packRaw ? requireObject(packRaw.limits, "pack.limits", errors) : undefined;
+    const pack = packRaw
+        ? {
+            default_depth: requireNumber(packRaw.default_depth, "pack.default_depth", errors),
+            default_edges: requireStringArray(packRaw.default_edges, "pack.default_edges", errors),
+            verbose_core_list_path: requireString(packRaw.verbose_core_list_path, "pack.verbose_core_list_path", errors),
+            limits: packLimitsRaw
+                ? {
+                    max_nodes: requireNumber(packLimitsRaw.max_nodes, "pack.limits.max_nodes", errors),
+                    max_bytes: requireNumber(packLimitsRaw.max_bytes, "pack.limits.max_bytes", errors),
+                }
+                : undefined,
+        }
+        : undefined;
+    const templates = templatesRaw
+        ? {
+            root_path: requireString(templatesRaw.root_path, "templates.root_path", errors),
+            default_set: requireString(templatesRaw.default_set, "templates.default_set", errors),
+            workspace_overrides_enabled: requireBoolean(templatesRaw.workspace_overrides_enabled, "templates.workspace_overrides_enabled", errors),
+        }
+        : undefined;
+    const workNextRaw = workRaw ? requireObject(workRaw.next, "work.next", errors) : undefined;
+    const work = workRaw
+        ? {
+            status_enum: requireStringArray(workRaw.status_enum, "work.status_enum", errors),
+            priority_min: requireNumber(workRaw.priority_min, "work.priority_min", errors),
+            priority_max: requireNumber(workRaw.priority_max, "work.priority_max", errors),
+            next: workNextRaw
+                ? {
+                    strategy: requireString(workNextRaw.strategy, "work.next.strategy", errors),
+                    status_preference: requireStringArray(workNextRaw.status_preference, "work.next.status_preference", errors),
+                }
+                : undefined,
+        }
+        : undefined;
+    const workspaces = {};
+    if (workspacesRaw) {
+        for (const [alias, entry] of Object.entries(workspacesRaw)) {
+            if (alias !== alias.toLowerCase()) {
+                errors.push(`workspaces.${alias} alias must be lowercase`);
+            }
+            const ws = requireObject(entry, `workspaces.${alias}`, errors);
+            if (!ws) {
+                continue;
+            }
+            const wsPath = requireString(ws.path, `workspaces.${alias}.path`, errors);
+            const wsEnabled = requireBoolean(ws.enabled, `workspaces.${alias}.enabled`, errors);
+            const wsMdkgDir = requireString(ws.mdkg_dir, `workspaces.${alias}.mdkg_dir`, errors);
+            if (wsPath && wsEnabled !== undefined && wsMdkgDir) {
+                workspaces[alias] = {
+                    path: wsPath,
+                    enabled: wsEnabled,
+                    mdkg_dir: wsMdkgDir,
+                };
+            }
+        }
+    }
+    if (errors.length > 0) {
+        throw new Error(`config validation failed:\n${errors.join("\n")}`);
+    }
+    return {
+        schema_version: schema_version,
+        tool: tool,
+        root_required: root_required,
+        index: index,
+        pack: pack,
+        templates: templates,
+        work: work,
+        workspaces,
+    };
+}
+function loadConfig(root) {
+    const path = (0, paths_1.configPath)(root);
+    if (!fs_1.default.existsSync(path)) {
+        throw new Error(`config not found at ${path}`);
+    }
+    let raw;
+    try {
+        raw = JSON.parse(fs_1.default.readFileSync(path, "utf8"));
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : "unknown error";
+        throw new Error(`failed to read config: ${message}`);
+    }
+    const migrated = (0, migrate_1.migrateConfig)(raw);
+    return validateConfigSchema(migrated.config);
+}

package/dist/core/migrate.js

@@ -0,0 +1,30 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LATEST_SCHEMA_VERSION = void 0;
+exports.migrateConfig = migrateConfig;
+exports.LATEST_SCHEMA_VERSION = 1;
+const MIGRATIONS = {};
+function migrateConfig(raw) {
+    if (typeof raw !== "object" || raw === null) {
+        throw new Error("config must be a JSON object");
+    }
+    const version = raw.schema_version;
+    if (typeof version !== "number" || !Number.isInteger(version)) {
+        throw new Error("config schema_version must be an integer");
+    }
+    if (version > exports.LATEST_SCHEMA_VERSION) {
+        throw new Error(`config schema_version ${version} is newer than supported ${exports.LATEST_SCHEMA_VERSION}`);
+    }
+    if (version === exports.LATEST_SCHEMA_VERSION) {
+        return { config: raw, from: version, to: version };
+    }
+    let current = raw;
+    for (let v = version; v < exports.LATEST_SCHEMA_VERSION; v += 1) {
+        const migrator = MIGRATIONS[v];
+        if (!migrator) {
+            throw new Error(`no migration available for schema_version ${v} -> ${v + 1}`);
+        }
+        current = migrator(current);
+    }
+    return { config: current, from: version, to: exports.LATEST_SCHEMA_VERSION };
+}

package/dist/core/paths.js

@@ -0,0 +1,14 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveRoot = resolveRoot;
+exports.configPath = configPath;
+const path_1 = __importDefault(require("path"));
+function resolveRoot(rootArg) {
+    return rootArg ? path_1.default.resolve(rootArg) : process.cwd();
+}
+function configPath(root) {
+    return path_1.default.join(root, ".mdkg", "config.json");
+}

package/dist/graph/edges.js

@@ -0,0 +1,64 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.extractEdges = extractEdges;
+const ID_REF_RE = /^([a-z][a-z0-9_]*:)?[a-z]+-[0-9]+$/;
+function formatError(filePath, key, message) {
+    return new Error(`${filePath}: ${key} ${message}`);
+}
+function normalizeIdRef(value, filePath, key) {
+    const normalized = value.toLowerCase();
+    if (normalized !== value) {
+        throw formatError(filePath, key, "must be lowercase");
+    }
+    if (!ID_REF_RE.test(normalized)) {
+        throw formatError(filePath, key, `invalid id reference: ${value}`);
+    }
+    return normalized;
+}
+function readString(fm, key) {
+    const value = fm[key];
+    if (value === undefined) {
+        return undefined;
+    }
+    if (typeof value !== "string") {
+        throw new Error(`${key} must be a string`);
+    }
+    return value;
+}
+function readStringList(fm, key) {
+    const value = fm[key];
+    if (value === undefined) {
+        return undefined;
+    }
+    if (!Array.isArray(value)) {
+        throw new Error(`${key} must be a list`);
+    }
+    return value;
+}
+function extractEdges(frontmatter, filePath) {
+    const epic = readString(frontmatter, "epic");
+    const parent = readString(frontmatter, "parent");
+    const prev = readString(frontmatter, "prev");
+    const next = readString(frontmatter, "next");
+    const relates = readStringList(frontmatter, "relates") ?? [];
+    const blocked_by = readStringList(frontmatter, "blocked_by") ?? [];
+    const blocks = readStringList(frontmatter, "blocks") ?? [];
+    const edges = {
+        relates: relates.map((value) => normalizeIdRef(value, filePath, "relates")),
+        blocked_by: blocked_by.map((value) => normalizeIdRef(value, filePath, "blocked_by")),
+        blocks: blocks.map((value) => normalizeIdRef(value, filePath, "blocks")),
+    };
+    if (epic) {
+        edges.epic = normalizeIdRef(epic, filePath, "epic");
+    }
+    if (parent) {
+        edges.parent = normalizeIdRef(parent, filePath, "parent");
+    }
+    if (prev) {
+        edges.prev = normalizeIdRef(prev, filePath, "prev");
+    }
+    if (next) {
+        edges.next = normalizeIdRef(next, filePath, "next");
+    }
+    return edges;
+}