@therocketcode/gsd-core 1.4.0

package/gsd-core/bin/lib/decisions.cjs

@@ -0,0 +1,118 @@
+"use strict";
+/**
+ * Shared parser for CONTEXT.md <decisions> blocks (ADR-457 build-at-publish:
+ * the hand-written bin/lib/decisions.cjs collapsed to a TypeScript source of
+ * truth). Behaviour is preserved byte-for-behaviour from the prior hand-written
+ * .cjs; only types are added.
+ *
+ * Accepts both numeric (D-42) and alphanumeric (D-INFRA-01) IDs.
+ * Returns {id, text, category, tags, trackable} per decision.
+ * CJS callers that only use {id, text} safely ignore the extra fields.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseDecisions = parseDecisions;
+const DISCRETION_HEADINGS = new Set([
+    "claude's discretion",
+    'claudes discretion',
+    'claude discretion',
+]);
+const NON_TRACKABLE_TAGS = new Set(['informational', 'folded', 'deferred']);
+/**
+ * Strip fenced code blocks from `content` so example `<decisions>` snippets
+ * inside ```` ``` ```` do not pollute the parser (review F11).
+ */
+function stripFencedCode(content) {
+    return content.replace(/```[\s\S]*?```/g, ' ').replace(/~~~[\s\S]*?~~~/g, ' ');
+}
+/**
+ * Extract the inner text of EVERY `<decisions>...</decisions>` block in
+ * order, concatenated by `\n\n`. Returns null when no block is present.
+ *
+ * CONTEXT.md may legitimately contain more than one block (for example, a
+ * "current decisions" block plus a "carry-over from prior phase" block);
+ * dropping all-but-the-first silently lost the second batch (review F13).
+ */
+function extractDecisionsBlock(content) {
+    const cleaned = stripFencedCode(content);
+    const matches = [...cleaned.matchAll(/<decisions>([\s\S]*?)<\/decisions>/g)];
+    if (matches.length === 0)
+        return null;
+    return matches.map((m) => m[1]).join('\n\n');
+}
+/**
+ * Parse trackable decisions from CONTEXT.md content.
+ *
+ * Returns ALL D-NN decisions found inside `<decisions>` (including
+ * non-trackable ones, with `trackable: false`). Callers that only want the
+ * gate-enforced decisions should filter `.filter(d => d.trackable)`.
+ */
+function parseDecisions(content) {
+    if (!content || typeof content !== 'string')
+        return [];
+    const block = extractDecisionsBlock(content);
+    if (block === null)
+        return [];
+    const lines = block.split(/\r?\n/);
+    const out = [];
+    let category = '';
+    let inDiscretion = false;
+    // Bullet line: `- **D-NN[ [tags]]:** text`
+    // Phase 6 (#3575): aligned to CJS regex — accepts alphanumeric IDs (D-01, D-INFRA-01, D-FOO_BAR)
+    // in addition to numeric-only IDs (D-42). The first character after `D-` must
+    // be alphanumeric, so malformed shapes like `D--foo` or `D-_bar` are rejected.
+    // CJS callers consume {id, text} and ignore the optional extras.
+    const bulletRe = /^\s*-\s+\*\*D-([A-Za-z0-9][A-Za-z0-9_-]*)(?:\s*\[([^\]]+)\])?\s*:\*\*\s*(.*)$/;
+    let current = null;
+    const flush = () => {
+        if (current) {
+            current.text = current.text.trim();
+            out.push(current);
+            current = null;
+        }
+    };
+    for (const line of lines) {
+        const trimmed = line.trim();
+        // Track category headings (`### Heading`)
+        const headingMatch = trimmed.match(/^###\s+(.+?)\s*$/);
+        if (headingMatch) {
+            flush();
+            category = headingMatch[1];
+            // Strip the full unicode-quote family so any rendering of "Claude's
+            // Discretion" (ASCII apostrophe, curly U+2019, U+2018, U+201A, U+201B,
+            // double-quote variants U+201C/D/E/F, etc.) collapses to the same key
+            // (review F20).
+            const normalized = category
+                .toLowerCase()
+                .replace(/[‘’‚‛“”„‟'"`]/g, '')
+                .trim();
+            inDiscretion = DISCRETION_HEADINGS.has(normalized);
+            continue;
+        }
+        const bulletMatch = line.match(bulletRe);
+        if (bulletMatch) {
+            flush();
+            const id = `D-${bulletMatch[1]}`;
+            const tags = bulletMatch[2]
+                ? bulletMatch[2]
+                    .split(',')
+                    .map((t) => t.trim().toLowerCase())
+                    .filter(Boolean)
+                : [];
+            const trackable = !inDiscretion && !tags.some((t) => NON_TRACKABLE_TAGS.has(t));
+            current = { id, text: bulletMatch[3], category, tags, trackable };
+            continue;
+        }
+        // Continuation line for current decision (indented with space OR tab,
+        // non-bullet, non-empty) — tab indentation must work too (review F12).
+        if (current && trimmed !== '' && !trimmed.startsWith('-') && /^[ \t]/.test(line)) {
+            current.text += ' ' + trimmed;
+            continue;
+        }
+        // Blank line or unrelated content terminates the current decision
+        if (trimmed === '') {
+            flush();
+        }
+    }
+    flush();
+    return out;
+}

package/gsd-core/bin/lib/docs.cjs

@@ -0,0 +1,252 @@
+"use strict";
+/**
+ * Docs — Commands for the docs-update workflow
+ *
+ * Provides `cmdDocsInit` which returns project signals, existing doc inventory
+ * with GSD marker detection, doc tooling detection, monorepo awareness, and
+ * model resolution. Used by Phase 2 to route doc generation appropriately.
+ *
+ * ADR-457 build-at-publish: the hand-written bin/lib/docs.cjs collapsed
+ * to a TypeScript source of truth. Behaviour is preserved byte-for-behaviour
+ * from the prior hand-written .cjs; only strict types are added.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const core = require("./core.cjs");
+const { output, loadConfig, resolveModelInternal, pathExistsInternal, toPosixPath, checkAgentsInstalled } = core;
+const shell_command_projection_cjs_1 = require("./shell-command-projection.cjs");
+// ─── Constants ────────────────────────────────────────────────────────────────
+const GSD_MARKER = '<!-- generated-by: gsd-doc-writer -->';
+const SKIP_DIRS = new Set([
+    'node_modules', '.git', '.planning', '.claude', '__pycache__',
+    'target', 'dist', 'build', '.next', '.nuxt', 'coverage',
+    '.vscode', '.idea',
+]);
+// ─── Private helpers ──────────────────────────────────────────────────────────
+/**
+ * Check whether a file begins with the GSD doc writer marker.
+ * Reads the first 500 bytes only — avoids loading large files.
+ */
+function hasGsdMarker(filePath) {
+    try {
+        const buf = Buffer.alloc(500);
+        const fd = node_fs_1.default.openSync(filePath, 'r');
+        const bytesRead = node_fs_1.default.readSync(fd, buf, 0, 500, 0);
+        node_fs_1.default.closeSync(fd);
+        return buf.slice(0, bytesRead).toString('utf-8').includes(GSD_MARKER);
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Recursively scan the project root (immediate .md files) and docs/ directory
+ * (up to 4 levels deep) for Markdown files, excluding dirs in SKIP_DIRS.
+ */
+function scanExistingDocs(cwd) {
+    const MAX_DEPTH = 4;
+    const results = [];
+    function walkDir(dir, depth) {
+        if (depth > MAX_DEPTH)
+            return;
+        try {
+            const entries = node_fs_1.default.readdirSync(dir, { withFileTypes: true });
+            for (const entry of entries) {
+                if (SKIP_DIRS.has(entry.name))
+                    continue;
+                const abs = node_path_1.default.join(dir, entry.name);
+                if (entry.isDirectory()) {
+                    walkDir(abs, depth + 1);
+                }
+                else if (entry.isFile() && entry.name.toLowerCase().endsWith('.md')) {
+                    const rel = toPosixPath(node_path_1.default.relative(cwd, abs));
+                    results.push({ path: rel, has_gsd_marker: hasGsdMarker(abs) });
+                }
+            }
+        }
+        catch { /* directory may not exist — best-effort */ }
+    }
+    // Scan root-level .md files (non-recursive)
+    try {
+        const entries = node_fs_1.default.readdirSync(cwd, { withFileTypes: true });
+        for (const entry of entries) {
+            if (entry.isFile() && entry.name.toLowerCase().endsWith('.md')) {
+                const abs = node_path_1.default.join(cwd, entry.name);
+                const rel = toPosixPath(node_path_1.default.relative(cwd, abs));
+                results.push({ path: rel, has_gsd_marker: hasGsdMarker(abs) });
+            }
+        }
+    }
+    catch { /* best-effort */ }
+    // Recursively scan docs/ directory
+    const docsDir = node_path_1.default.join(cwd, 'docs');
+    walkDir(docsDir, 1);
+    // Fallback: if docs/ does not exist, try documentation/ or doc/
+    try {
+        node_fs_1.default.statSync(docsDir);
+    }
+    catch {
+        const alternatives = ['documentation', 'doc'];
+        for (const alt of alternatives) {
+            const altDir = node_path_1.default.join(cwd, alt);
+            try {
+                const stat = node_fs_1.default.statSync(altDir);
+                if (stat.isDirectory()) {
+                    walkDir(altDir, 1);
+                    break;
+                }
+            }
+            catch { /* not present */ }
+        }
+    }
+    return results.sort((a, b) => a.path.localeCompare(b.path));
+}
+/**
+ * Detect project type signals from the filesystem and package.json.
+ * All checks are best-effort and never throw.
+ */
+function detectProjectType(cwd) {
+    const exists = (rel) => {
+        try {
+            return pathExistsInternal(cwd, rel);
+        }
+        catch {
+            return false;
+        }
+    };
+    // Read package.json once — used by has_cli_bin, is_monorepo, has_tests checks.
+    const pkgRaw = (0, shell_command_projection_cjs_1.platformReadSync)(node_path_1.default.join(cwd, 'package.json'));
+    let pkg = null;
+    if (pkgRaw) {
+        try {
+            pkg = JSON.parse(pkgRaw);
+        }
+        catch { /* invalid JSON */ }
+    }
+    // has_cli_bin: package.json has a `bin` field
+    const binField = pkg?.['bin'];
+    const has_cli_bin = !!(binField && (typeof binField === 'string' ||
+        (typeof binField === 'object' && Object.keys(binField).length > 0)));
+    // is_monorepo: pnpm-workspace.yaml, lerna.json, or package.json workspaces
+    let is_monorepo = exists('pnpm-workspace.yaml') || exists('lerna.json');
+    if (!is_monorepo && pkg) {
+        is_monorepo = Array.isArray(pkg['workspaces']) && pkg['workspaces'].length > 0;
+    }
+    // has_tests: common test directories or test frameworks in devDependencies
+    let has_tests = exists('test') || exists('tests') || exists('__tests__') || exists('spec');
+    if (!has_tests && pkg) {
+        const devDeps = Object.keys(pkg['devDependencies'] || {});
+        has_tests = devDeps.some(d => ['vitest', 'jest', 'mocha', 'jasmine', 'ava'].includes(d));
+    }
+    // has_deploy_config: various deployment config files
+    const deployFiles = [
+        'Dockerfile', 'docker-compose.yml', 'docker-compose.yaml',
+        'fly.toml', 'render.yaml', 'vercel.json', 'netlify.toml', 'railway.json',
+        '.github/workflows/deploy.yml', '.github/workflows/deploy.yaml',
+    ];
+    const has_deploy_config = deployFiles.some(f => exists(f));
+    return {
+        has_package_json: exists('package.json'),
+        has_api_routes: (exists('src/app/api') || exists('routes') || exists('src/routes') ||
+            exists('api') || exists('server')),
+        has_cli_bin,
+        is_open_source: exists('LICENSE') || exists('LICENSE.md'),
+        has_deploy_config,
+        is_monorepo,
+        has_tests,
+    };
+}
+/**
+ * Detect known documentation tooling in the project.
+ */
+function detectDocTooling(cwd) {
+    const exists = (rel) => {
+        try {
+            return pathExistsInternal(cwd, rel);
+        }
+        catch {
+            return false;
+        }
+    };
+    return {
+        docusaurus: exists('docusaurus.config.js') || exists('docusaurus.config.ts'),
+        vitepress: (exists('.vitepress/config.js') ||
+            exists('.vitepress/config.ts') ||
+            exists('.vitepress/config.mts')),
+        mkdocs: exists('mkdocs.yml'),
+        storybook: exists('.storybook'),
+    };
+}
+/**
+ * Extract monorepo workspace globs from pnpm-workspace.yaml, package.json
+ * workspaces, or lerna.json.
+ */
+function detectMonorepoWorkspaces(cwd) {
+    // pnpm-workspace.yaml
+    const pnpmRaw = (0, shell_command_projection_cjs_1.platformReadSync)(node_path_1.default.join(cwd, 'pnpm-workspace.yaml'));
+    if (pnpmRaw) {
+        const workspaces = [];
+        for (const line of pnpmRaw.split('\n')) {
+            const m = line.match(/^\s*-\s+['"]?(.+?)['"]?\s*$/);
+            if (m)
+                workspaces.push(m[1].trim());
+        }
+        if (workspaces.length > 0)
+            return workspaces;
+    }
+    // package.json workspaces
+    const pkgRaw = (0, shell_command_projection_cjs_1.platformReadSync)(node_path_1.default.join(cwd, 'package.json'));
+    if (pkgRaw) {
+        try {
+            const pkg = JSON.parse(pkgRaw);
+            if (Array.isArray(pkg['workspaces']) && pkg['workspaces'].length > 0) {
+                return pkg['workspaces'];
+            }
+        }
+        catch { /* invalid JSON */ }
+    }
+    // lerna.json
+    const lernaRaw = (0, shell_command_projection_cjs_1.platformReadSync)(node_path_1.default.join(cwd, 'lerna.json'));
+    if (lernaRaw) {
+        try {
+            const lerna = JSON.parse(lernaRaw);
+            if (Array.isArray(lerna['packages']) && lerna['packages'].length > 0) {
+                return lerna['packages'];
+            }
+        }
+        catch { /* invalid JSON */ }
+    }
+    return [];
+}
+// ─── Public commands ──────────────────────────────────────────────────────────
+/**
+ * Return JSON context for the docs-update workflow: project signals, existing
+ * doc inventory, doc tooling detection, monorepo workspaces, and model
+ * resolution. Follows the cmdInitMapCodebase pattern.
+ *
+ * @example
+ * node gsd-tools.cjs docs-init --raw
+ */
+function cmdDocsInit(cwd, raw) {
+    const config = loadConfig(cwd);
+    const result = {
+        doc_writer_model: resolveModelInternal(cwd, 'gsd-doc-writer'),
+        commit_docs: config.commit_docs,
+        existing_docs: scanExistingDocs(cwd),
+        project_type: detectProjectType(cwd),
+        doc_tooling: detectDocTooling(cwd),
+        monorepo_workspaces: detectMonorepoWorkspaces(cwd),
+        planning_exists: pathExistsInternal(cwd, '.planning'),
+    };
+    // Inject project_root and agent installation status (mirrors withProjectRoot in init.cjs)
+    result['project_root'] = cwd;
+    const agentStatus = checkAgentsInstalled();
+    result['agents_installed'] = agentStatus.agents_installed;
+    result['missing_agents'] = agentStatus.missing_agents;
+    output(result, raw, undefined);
+}
+module.exports = { cmdDocsInit };