@guilhermefsousa/open-spec-kit 0.0.1

package/src/parsers/markdown-sections.js

@@ -0,0 +1,271 @@
+/**
+ * Markdown Section Parser
+ *
+ * Parses markdown into a hierarchical section tree with heading hierarchy,
+ * code fence awareness, and table extraction.
+ *
+ * This is the foundation for all 32 Zod validation rules in osk validate.
+ */
+
+// --- Code Fence Mask ---
+
+/**
+ * Build a boolean mask marking lines inside code fences.
+ * Lines inside ``` or ~~~ blocks are marked true — headings there are ignored.
+ * @param {string[]} lines
+ * @returns {boolean[]}
+ */
+export function buildCodeFenceMask(lines) {
+  const mask = new Array(lines.length).fill(false);
+  let inFence = false;
+  let fenceMarker = null; // '`' or '~'
+  let fenceLen = 0;
+
+  for (let i = 0; i < lines.length; i++) {
+    const trimmed = lines[i].trimStart();
+
+    if (!inFence) {
+      const open = trimmed.match(/^(`{3,}|~{3,})/);
+      if (open) {
+        inFence = true;
+        fenceMarker = open[1][0];
+        fenceLen = open[1].length;
+        mask[i] = true;
+        continue;
+      }
+    } else {
+      mask[i] = true;
+      // Check for closing fence: same marker, same or greater length, nothing after
+      const close = trimmed.match(/^(`{3,}|~{3,})\s*$/);
+      if (close && close[1][0] === fenceMarker && close[1].length >= fenceLen) {
+        inFence = false;
+        fenceMarker = null;
+        fenceLen = 0;
+      }
+    }
+  }
+
+  return mask;
+}
+
+// --- Section Parsing ---
+
+/**
+ * @typedef {Object} Section
+ * @property {number} level - Heading level (1-6)
+ * @property {string} title - Heading text (without # prefix)
+ * @property {string} content - All content until next heading of same/higher level
+ * @property {Section[]} children - Nested subsections
+ */
+
+const HEADING_RE = /^(#{1,6})\s+(.+)$/;
+
+/**
+ * Parse markdown into hierarchical section tree.
+ * Respects code fences (ignores headings inside them).
+ * @param {string} markdown - Raw file content
+ * @returns {Section[]} - Tree of sections
+ */
+export function parseSections(markdown) {
+  // Normalize CRLF → LF so headings aren't broken by trailing \r.
+  // Both `.` and `$` in JS regex treat \r as a line terminator,
+  // causing HEADING_RE to fail on lines ending with \r.
+  const lines = markdown.split(/\r?\n/);
+  const mask = buildCodeFenceMask(lines);
+  const rootChildren = [];
+
+  /** @type {{ level: number, section: Section }[]} */
+  const stack = [];
+
+  let currentContentLines = [];
+
+  function flushContent() {
+    if (stack.length > 0) {
+      stack[stack.length - 1].section.content = currentContentLines.join('\n').trim();
+    }
+    currentContentLines = [];
+  }
+
+  for (let i = 0; i < lines.length; i++) {
+    if (mask[i]) {
+      currentContentLines.push(lines[i]);
+      continue;
+    }
+
+    const match = lines[i].match(HEADING_RE);
+    if (!match) {
+      currentContentLines.push(lines[i]);
+      continue;
+    }
+
+    flushContent();
+
+    const level = match[1].length;
+    const title = match[2].trim();
+    const section = { level, title, content: '', children: [] };
+
+    // Pop stack until we find a parent with lower level
+    while (stack.length > 0 && stack[stack.length - 1].level >= level) {
+      stack.pop();
+    }
+
+    if (stack.length === 0) {
+      rootChildren.push(section);
+    } else {
+      stack[stack.length - 1].section.children.push(section);
+    }
+
+    stack.push({ level, section });
+  }
+
+  flushContent();
+
+  return rootChildren;
+}
+
+// --- Section Search ---
+
+/**
+ * Find first section matching a title pattern (case-insensitive).
+ * Searches recursively through the tree.
+ * @param {Section[]} sections
+ * @param {RegExp} pattern
+ * @returns {Section|null}
+ */
+export function findSection(sections, pattern) {
+  for (const section of sections) {
+    if (pattern.test(section.title)) return section;
+    const found = findSection(section.children, pattern);
+    if (found) return found;
+  }
+  return null;
+}
+
+/**
+ * Collect all sections matching a pattern recursively.
+ * @param {Section[]} sections
+ * @param {RegExp} pattern
+ * @returns {Section[]}
+ */
+export function findAllSections(sections, pattern) {
+  const results = [];
+  for (const section of sections) {
+    if (pattern.test(section.title)) results.push(section);
+    results.push(...findAllSections(section.children, pattern));
+  }
+  return results;
+}
+
+/**
+ * Get all sections at a specific heading level (non-recursive, top-level only).
+ * @param {Section[]} sections
+ * @param {number} level
+ * @returns {Section[]}
+ */
+export function getSectionsByLevel(sections, level) {
+  const results = [];
+  for (const section of sections) {
+    if (section.level === level) results.push(section);
+  }
+  return results;
+}
+
+// --- Table Parsing ---
+
+const TABLE_SEP_RE = /^\|?\s*[-:]+[-| :]*$/;
+
+/**
+ * Extract markdown table from content into array of objects.
+ * Handles: | Header1 | Header2 | with separator row |---|---|
+ * @param {string} content - Section content (may contain multiple tables)
+ * @returns {Object[]} - Rows as key-value objects using headers as keys
+ */
+export function parseTable(content) {
+  const lines = content.split('\n');
+  const rows = [];
+  let headers = null;
+  let inTable = false;
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i].trim();
+
+    if (!inTable) {
+      // Look for header row: must have | and the next line must be separator
+      if (line.includes('|') && i + 1 < lines.length && TABLE_SEP_RE.test(lines[i + 1].trim())) {
+        headers = splitTableRow(line);
+        inTable = true;
+        i++; // skip separator
+        continue;
+      }
+    } else {
+      // We're in a table — read data rows until empty line or non-table line
+      if (!line || !line.includes('|')) {
+        inTable = false;
+        headers = null;
+        continue;
+      }
+      if (TABLE_SEP_RE.test(line)) continue; // skip extra separators
+
+      const cells = splitTableRow(line);
+      const row = {};
+      for (let j = 0; j < headers.length; j++) {
+        const key = headers[j].toLowerCase().normalize('NFD').replace(/[\u0300-\u036f]/g, '').replace(/\s+/g, '_');
+        row[key] = j < cells.length ? cells[j] : '';
+      }
+      rows.push(row);
+    }
+  }
+
+  return rows;
+}
+
+/**
+ * Split a markdown table row into cell values.
+ * @param {string} line
+ * @returns {string[]}
+ */
+function splitTableRow(line) {
+  return line
+    .replace(/^\|/, '')
+    .replace(/\|$/, '')
+    .split('|')
+    .map(cell => cell.trim());
+}
+
+// --- Utility ---
+
+/**
+ * Extract all regex matches from content.
+ * @param {string} content
+ * @param {RegExp} pattern - Must have global flag
+ * @returns {string[]} - Unique matches
+ */
+export function extractUniqueMatches(content, pattern) {
+  return [...new Set((content.match(pattern) || []))];
+}
+
+/**
+ * Check if content contains any of the unresolved marker keywords.
+ * @param {string} content
+ * @returns {{ found: boolean, markers: string[] }}
+ */
+export function findUnresolvedMarkers(content) {
+  const MARKER_RE = /\b(MOCKADO|TODO|A CONFIRMAR|TBD|FIXME|PLACEHOLDER|TKTK)\b/gi;
+  const matches = content.match(MARKER_RE) || [];
+  const unique = [...new Set(matches.map(m => m.toUpperCase()))];
+  return { found: unique.length > 0, markers: unique };
+}
+
+/**
+ * Get full raw content of a section including its children (reconstructed).
+ * Useful for checking content within a section and all its subsections.
+ * @param {Section} section
+ * @returns {string}
+ */
+export function getSectionFullContent(section) {
+  let content = section.content;
+  for (const child of section.children) {
+    content += '\n' + '#'.repeat(child.level) + ' ' + child.title + '\n' + getSectionFullContent(child);
+  }
+  return content;
+}

package/src/schemas/projects.schema.js

@@ -0,0 +1,111 @@
+/**
+ * Zod schema for projects.yml
+ *
+ * Central config file read by all components.
+ * Validated by `open-spec-kit validate` and `open-spec-kit doctor`.
+ */
+
+import { z } from 'zod';
+import { parse as parseYaml } from 'yaml';
+
+export const RepoSchema = z.object({
+  name: z.string().min(1),
+  stack: z.string().optional(),
+  type: z.string().optional(),
+  purpose: z.string().optional(),
+  status: z.enum(['planned', 'active', 'deprecated']).optional(),
+  url: z.string().nullable().optional(),
+});
+
+export const CodingAgentsSchema = z.record(
+  z.string(), // stack keyword (e.g., "dotnet", "nodejs")
+  z.string(), // agent name (e.g., "dotnet-engineer")
+).optional();
+
+export const AgentsSchema = z.object({
+  coding: CodingAgentsSchema,
+  security: z.string().nullable().optional(),
+  code_review: z.string().nullable().optional(),
+  design_doc: z.string().nullable().optional(),
+  principal: z.string().nullable().optional(),
+}).optional();
+
+export const ProjectsSchema = z.object({
+  project: z.object({
+    name: z.string().min(1),
+    sigla: z.string().min(2).max(4).optional(),
+    domain: z.string().optional(),
+    status: z.string().optional(),
+    team_size: z.number().optional(),
+    preset: z.enum(['lean', 'standard', 'enterprise']).default('standard'),
+    stack: z.array(z.string()).optional(),
+    agents: z.array(z.string()).optional(), // platforms: claude, copilot
+  }).optional(),
+  specs: z.object({
+    preset: z.enum(['lean', 'standard', 'enterprise']).default('standard'),
+  }).optional(),
+  repos: z.array(RepoSchema).optional(),
+  agents: AgentsSchema,
+  confluence: z.object({
+    space: z.string().optional(),
+    root_page_id: z.union([z.string(), z.number()]).optional(),
+  }).optional(),
+});
+
+/**
+ * Parse projects.yml content and validate with Zod.
+ * @param {string} yamlContent - Raw YAML string
+ * @returns {{ data: object|null, errors: import('zod').ZodIssue[]|null, preset: string, repoNames: string[], repoStacks: Map<string, string> }}
+ */
+export function parseAndValidateProjects(yamlContent) {
+  let parsed;
+  try {
+    parsed = parseYaml(yamlContent);
+  } catch (e) {
+    return {
+      data: null,
+      errors: [{ path: ['projects.yml'], message: `YAML parse error: ${e.message}`, code: 'custom' }],
+      preset: 'standard',
+      repoNames: [],
+      repoStacks: new Map(),
+    };
+  }
+
+  const result = ProjectsSchema.safeParse(parsed);
+
+  if (!result.success) {
+    return {
+      data: parsed,
+      errors: result.error.issues,
+      preset: extractPreset(parsed),
+      repoNames: extractRepoNames(parsed),
+      repoStacks: extractRepoStacks(parsed),
+    };
+  }
+
+  return {
+    data: result.data,
+    errors: null,
+    preset: extractPreset(result.data),
+    repoNames: extractRepoNames(result.data),
+    repoStacks: extractRepoStacks(result.data),
+  };
+}
+
+function extractPreset(data) {
+  return data?.specs?.preset || data?.project?.preset || 'standard';
+}
+
+function extractRepoNames(data) {
+  return (data?.repos || []).map(r => r.name).filter(Boolean);
+}
+
+function extractRepoStacks(data) {
+  const map = new Map();
+  for (const repo of data?.repos || []) {
+    if (repo.name && repo.stack) {
+      map.set(repo.name, repo.stack);
+    }
+  }
+  return map;
+}