upcontent 0.0.0-stage → 0.1.0

package/src/lib/rehype-callouts.ts

@@ -0,0 +1,61 @@
+import { visit } from 'unist-util-visit'
+
+interface HastText {
+  type: 'text'
+  value: string
+}
+
+interface HastElement {
+  type: 'element'
+  tagName: string
+  properties?: Record<string, unknown>
+  children: (HastElement | HastText)[]
+}
+
+const ICONS: Record<string, string> = {
+  info: 'ℹ️',
+  note: '📝',
+  warning: '⚠️',
+  danger: '🚨',
+  tip: '💡',
+  important: '❗',
+  caution: '⚠️',
+}
+
+// Rehype plugin: converts > [!type] Title callouts (formato Obsidian) AFTER remark-to-rehype
+export function rehypeCallouts() {
+  return (tree: HastElement) => {
+    visit(tree, 'element', (node: HastElement) => {
+      if (node.tagName !== 'blockquote') return
+      const firstP = node.children?.find((c): c is HastElement => c.type === 'element' && c.tagName === 'p')
+      if (!firstP) return
+      const firstText = firstP.children?.find((c): c is HastText => c.type === 'text')
+      if (!firstText) return
+      const match = firstText.value.match(/^\[!([\w]+)\](?:\s+(.+))?/)
+      if (!match) return
+
+      const type = match[1].toLowerCase()
+      const titleText = match[2]?.trim() ?? (type.charAt(0).toUpperCase() + type.slice(1))
+      const afterMarker = firstText.value.replace(/^\[![\w]+\][^\n]*\n?/, '').trimStart()
+
+      if (afterMarker) {
+        firstText.value = afterMarker
+      } else {
+        firstP.children = firstP.children.filter(c => c !== firstText)
+        if (firstP.children.length === 0) node.children = node.children.filter(c => c !== firstP)
+      }
+
+      node.tagName = 'div'
+      node.properties = { className: [`callout`, `callout-${type}`] }
+
+      node.children.unshift({
+        type: 'element', tagName: 'div',
+        properties: { className: ['callout-title'] },
+        children: [
+          { type: 'element', tagName: 'span', properties: {}, children: [{ type: 'text', value: ICONS[type] ?? 'ℹ️' }] },
+          { type: 'text', value: ' ' + titleText },
+        ],
+      })
+    })
+  }
+}

package/src/lib/remark-strip-duplicate-title.test.ts

@@ -0,0 +1,73 @@
+import { describe, it, expect } from 'vitest'
+import { unified } from 'unified'
+import remarkParse from 'remark-parse'
+import remarkRehype from 'remark-rehype'
+import rehypeStringify from 'rehype-stringify'
+import { remarkStripDuplicateTitle, stripDuplicateTitle } from './remark-strip-duplicate-title'
+
+describe('stripDuplicateTitle', () => {
+  it('remove o primeiro H1 quando o texto bate com o title', () => {
+    const tree = {
+      children: [
+        { type: 'heading', depth: 1, children: [{ type: 'text', value: 'Meu Título' }] },
+        { type: 'paragraph', children: [{ type: 'text', value: 'corpo' }] },
+      ],
+    }
+    const removed = stripDuplicateTitle(tree, 'Meu Título')
+    expect(removed).toBe(true)
+    expect(tree.children).toHaveLength(1)
+    expect(tree.children[0].type).toBe('paragraph')
+  })
+
+  it('mantém o H1 quando o texto é diferente do title', () => {
+    const tree = {
+      children: [{ type: 'heading', depth: 1, children: [{ type: 'text', value: 'Outro título' }] }],
+    }
+    const removed = stripDuplicateTitle(tree, 'Meu Título')
+    expect(removed).toBe(false)
+    expect(tree.children).toHaveLength(1)
+  })
+
+  it('não remove H2 ou heading que não seja o primeiro nó', () => {
+    const tree = {
+      children: [
+        { type: 'paragraph', children: [{ type: 'text', value: 'intro' }] },
+        { type: 'heading', depth: 1, children: [{ type: 'text', value: 'Meu Título' }] },
+      ],
+    }
+    expect(stripDuplicateTitle(tree, 'Meu Título')).toBe(false)
+    expect(tree.children).toHaveLength(2)
+  })
+
+  it('sem title, não faz nada', () => {
+    const tree = {
+      children: [{ type: 'heading', depth: 1, children: [{ type: 'text', value: 'Meu Título' }] }],
+    }
+    expect(stripDuplicateTitle(tree, undefined)).toBe(false)
+    expect(tree.children).toHaveLength(1)
+  })
+})
+
+function render(markdown: string, title: string | undefined): string {
+  const file = { value: markdown, data: { astro: { frontmatter: { title } } } }
+  return unified()
+    .use(remarkParse)
+    .use(remarkStripDuplicateTitle)
+    .use(remarkRehype)
+    .use(rehypeStringify)
+    .processSync(file)
+    .toString()
+}
+
+describe('remarkStripDuplicateTitle (integração markdown → HTML)', () => {
+  it('remove o H1 duplicado, mantém o resto do corpo', () => {
+    const html = render('# Guia X\n\nConteúdo real.', 'Guia X')
+    expect(html).not.toContain('<h1>')
+    expect(html).toContain('Conteúdo real.')
+  })
+
+  it('sem duplicação, o H1 permanece intacto', () => {
+    const html = render('# Guia X\n\nConteúdo real.', 'Outro Título')
+    expect(html).toContain('<h1>Guia X</h1>')
+  })
+})

package/src/lib/remark-strip-duplicate-title.ts

@@ -0,0 +1,37 @@
+interface MdastNode {
+  type: string
+  depth?: number
+  value?: string
+  children?: MdastNode[]
+}
+
+function flattenText(node: MdastNode): string {
+  if (typeof node.value === 'string') return node.value
+  return (node.children ?? []).map(flattenText).join('')
+}
+
+// Pura, testável separadamente do vfile do Astro.
+export function stripDuplicateTitle(tree: { children: MdastNode[] }, title: string | undefined): boolean {
+  if (!title) return false
+  const first = tree.children[0]
+  if (!first || first.type !== 'heading' || first.depth !== 1) return false
+  if (flattenText(first).trim() !== title.trim()) return false
+  tree.children.splice(0, 1)
+  return true
+}
+
+// Muito conteúdo real tem title no frontmatter E repete o mesmo texto como
+// primeiro `# H1` do corpo (hábito de markdown feito pra ser lido standalone,
+// fora do Starlight) — o Starlight já renderiza o title do frontmatter no
+// topo da página, então esse H1 duplicado só produz o título repetido duas
+// vezes. Remove o H1 do corpo só quando o texto bate exatamente com o title.
+export function remarkStripDuplicateTitle() {
+  // tree/file tipados como `any` — o tipo genérico `Node` do unified não
+  // garante `children`, então um parâmetro estreito quebra a resolução de
+  // overload do Plugin (mesmo problema não aparece nos outros plugins deste
+  // projeto porque eles vivem em astro.config.mjs, sem checagem de tipo).
+  return (tree: any, file: any) => {
+    const title = file?.data?.astro?.frontmatter?.title
+    stripDuplicateTitle(tree, typeof title === 'string' ? title : undefined)
+  }
+}

package/src/lib/remark-structured-data-preview.test.ts

@@ -0,0 +1,104 @@
+import { describe, it, expect } from 'vitest'
+import { unified } from 'unified'
+import remarkParse from 'remark-parse'
+import remarkRehype from 'remark-rehype'
+import rehypeStringify from 'rehype-stringify'
+import { remarkStructuredDataPreview, tryRenderStructuredData } from './remark-structured-data-preview'
+
+function render(markdown: string): string {
+  return unified()
+    .use(remarkParse)
+    .use(remarkStructuredDataPreview)
+    .use(remarkRehype, { allowDangerousHtml: true })
+    .use(rehypeStringify, { allowDangerousHtml: true })
+    .processSync(markdown)
+    .toString()
+}
+
+describe('tryRenderStructuredData', () => {
+  it('JSON válido → retorna a árvore renderizada', () => {
+    const html = tryRenderStructuredData('json', '{"a": 1}')
+    expect(html).toContain('sdp-root')
+  })
+
+  it('YAML válido → retorna a árvore renderizada', () => {
+    const html = tryRenderStructuredData('yaml', 'a: 1\nb: 2')
+    expect(html).toContain('sdp-root')
+  })
+
+  it('JSON malformado → retorna null (fallback)', () => {
+    expect(tryRenderStructuredData('json', '{ invalido')).toBeNull()
+  })
+
+  it('YAML malformado → retorna null (fallback)', () => {
+    expect(tryRenderStructuredData('yaml', ':\n  - broken: [')).toBeNull()
+  })
+
+  it('linguagem não suportada → retorna null, nunca tenta parsear', () => {
+    expect(tryRenderStructuredData('typescript', 'const x = 1')).toBeNull()
+  })
+
+  it('bloco vazio → retorna null (nada estrutural pra mostrar)', () => {
+    expect(tryRenderStructuredData('yaml', '')).toBeNull()
+  })
+
+  it('bloco de uma linha ainda recebe o tratamento (sem threshold de tamanho)', () => {
+    expect(tryRenderStructuredData('json', '{"x":1}')).toContain('sdp-root')
+  })
+
+  it('CSV válido → retorna a tabela renderizada', () => {
+    const html = tryRenderStructuredData('csv', 'nome,idade\nAna,30')
+    expect(html).toContain('sdp-csv-table')
+  })
+
+  it('CSV com campo entre aspas contendo vírgula é tratado corretamente', () => {
+    const html = tryRenderStructuredData('csv', 'nome,cidade\n"Ana, Silva",SP')
+    expect(html).toContain('<td>Ana, Silva</td>')
+    expect(html).toContain('<td>SP</td>')
+  })
+
+  it('CSV vazio → retorna null (fallback)', () => {
+    expect(tryRenderStructuredData('csv', '')).toBeNull()
+  })
+
+  it('CSV com linhas de tamanho inconsistente → retorna null (fallback)', () => {
+    expect(tryRenderStructuredData('csv', 'a,b,c\n1,2')).toBeNull()
+  })
+})
+
+describe('remarkStructuredDataPreview (integração markdown → HTML)', () => {
+  it('bloco ```json válido vira árvore, não bloco de código', () => {
+    const html = render('```json\n{"nome": "Ana"}\n```')
+    expect(html).toContain('sdp-root')
+    expect(html).not.toContain('<code')
+  })
+
+  it('bloco ```yaml válido vira árvore', () => {
+    const html = render('```yaml\nnome: Ana\nidade: 30\n```')
+    expect(html).toContain('sdp-root')
+  })
+
+  it('JSON malformado cai no bloco de código normal, sem quebrar o build', () => {
+    const html = render('```json\n{ isso não é json }\n```')
+    expect(html).not.toContain('sdp-root')
+    expect(html).toContain('<code')
+  })
+
+  it('outras linguagens (ts, kotlin) não são tocadas pelo plugin', () => {
+    const html = render('```ts\nconst x = 1\n```')
+    expect(html).not.toContain('sdp-root')
+    expect(html).toContain('<code')
+  })
+
+  it('bloco ```csv válido vira tabela, não bloco de código', () => {
+    const html = render('```csv\nnome,idade\nAna,30\n```')
+    expect(html).toContain('sdp-csv-table')
+    expect(html).not.toContain('<code')
+  })
+
+  it('CSV inconsistente cai no bloco de código normal, sem quebrar o build', () => {
+    const html = render('```csv\na,b,c\n1,2\n```')
+    expect(html).not.toContain('sdp-csv-table')
+    expect(html).toContain('<code')
+  })
+})

package/src/lib/remark-structured-data-preview.ts

@@ -0,0 +1,66 @@
+import { JSON_SCHEMA, load as loadYaml } from 'js-yaml'
+import Papa from 'papaparse'
+import { visit } from 'unist-util-visit'
+import { renderCsvTable, renderStructuredDataTree } from './structured-data-tree'
+
+interface MdastCode {
+  type: 'code'
+  lang?: string | null
+  value: string
+}
+
+interface MdastParent {
+  type: string
+  children: unknown[]
+}
+
+const SUPPORTED_LANGS = new Set(['json', 'yaml', 'yml', 'csv'])
+
+// CSV vazio, com colunas inconsistentes entre linhas, ou que o papaparse não
+// consegue parsear cai no tratamento padrão de código (retorna null) — sem
+// threshold de tamanho, mas exige uma estrutura tabular coerente.
+function tryRenderCsv(source: string): string | null {
+  const { data, errors } = Papa.parse<string[]>(source.trim(), { skipEmptyLines: true })
+  if (errors.length > 0 || data.length === 0) return null
+
+  const width = data[0].length
+  if (width === 0 || data.some(row => row.length !== width)) return null
+
+  return renderCsvTable(data)
+}
+
+// Tenta parsear e renderizar a árvore — retorna null quando o conteúdo não é
+// válido no formato (ou a linguagem não é suportada), sinalizando pro
+// caller manter o bloco de código como está (fallback pro highlighting normal).
+export function tryRenderStructuredData(lang: string | null | undefined, source: string): string | null {
+  const normalizedLang = lang?.toLowerCase()
+  if (!normalizedLang || !SUPPORTED_LANGS.has(normalizedLang)) return null
+
+  if (normalizedLang === 'csv') return tryRenderCsv(source)
+
+  try {
+    // JSON_SCHEMA: restringe a tipos equivalentes a JSON (sem !!timestamp virando
+    // Date, sem tags YAML exóticas) — js-yaml v4 já não expõe nenhum tipo
+    // inseguro (removido da lib), isso é só previsibilidade, não segurança.
+    const parsed = normalizedLang === 'json' ? JSON.parse(source) : loadYaml(source, { schema: JSON_SCHEMA })
+    if (parsed === undefined) return null // bloco vazio ou só comentários (YAML) — nada estrutural pra mostrar
+    return renderStructuredDataTree(parsed, source)
+  } catch {
+    return null
+  }
+}
+
+// Remark plugin: converte ```json / ```yaml em árvore estática (<details>
+// aninhado), no mesmo esquema que remarkMermaid usa pra ```mermaid — troca
+// o nó 'code' por um nó 'html' ANTES do remark-rehype/Expressive Code
+// processarem o bloco, então eles nunca veem o bloco original.
+export function remarkStructuredDataPreview() {
+  return (tree: MdastParent) => {
+    visit(tree, 'code', (node: MdastCode, index: number | undefined, parent: MdastParent | undefined) => {
+      const html = tryRenderStructuredData(node.lang, node.value)
+      if (html === null || !parent || index === undefined) return
+      parent.children.splice(index, 1, { type: 'html', value: html })
+      return index + 1
+    })
+  }
+}

package/src/lib/remark-wiki-links.test.ts

@@ -0,0 +1,102 @@
+import { describe, it, expect } from 'vitest'
+import { unified } from 'unified'
+import remarkParse from 'remark-parse'
+import remarkRehype from 'remark-rehype'
+import rehypeStringify from 'rehype-stringify'
+import { remarkWikiLinks } from './remark-wiki-links'
+
+function render(markdown: string): string {
+  return unified()
+    .use(remarkParse)
+    .use(remarkWikiLinks)
+    .use(remarkRehype)
+    .use(rehypeStringify)
+    .processSync(markdown)
+    .toString()
+}
+
+function renderStrict(markdown: string): string {
+  return unified()
+    .use(remarkParse)
+    .use(remarkWikiLinks, { contentRoot: process.cwd(), failOnBrokenLinks: true })
+    .use(remarkRehype)
+    .use(rehypeStringify)
+    .processSync(markdown)
+    .toString()
+}
+
+describe('remarkWikiLinks', () => {
+  it('resolve [[page]] simples pra /page', () => {
+    const html = render('Veja [[backend/plan]] pra mais detalhes.')
+    expect(html).toContain('href="/backend/plan"')
+    expect(html).toContain('>backend/plan<')
+  })
+
+  it('resolve [[page#heading]] combinando path e anchor', () => {
+    const html = render('Ver [[DESIGN-licencas#Impact Summary]].')
+    expect(html).toContain('href="/design-licencas#impact-summary"')
+  })
+
+  it('resolve [[#heading]] como anchor local, sem path', () => {
+    const html = render('Ver [[#Contracts]] abaixo.')
+    expect(html).toContain('href="#contracts"')
+  })
+
+  it('resolve [[page|label]] usando o label como texto do link', () => {
+    const html = render('Veja [[backend/plan|o plano]] aqui.')
+    expect(html).toContain('href="/backend/plan"')
+    expect(html).toContain('>o plano<')
+  })
+
+  it('normaliza espaços e maiúsculas no path', () => {
+    const html = render('Ver [[Meu Documento]].')
+    expect(html).toContain('href="/meu-documento"')
+  })
+
+  it('não afeta texto sem wiki links', () => {
+    const html = render('Texto normal sem links especiais.')
+    expect(html).not.toContain('<a ')
+    expect(html).toContain('Texto normal sem links especiais.')
+  })
+
+  it('resolve múltiplos wiki links na mesma linha', () => {
+    const html = render('Ver [[a]] e também [[b]].')
+    expect(html).toContain('href="/a"')
+    expect(html).toContain('href="/b"')
+  })
+
+  // não corrompe rótulos de diagrama Mermaid que usam [[texto]] (sintaxe de subroutine node) —
+  // o conteúdo de um bloco de código é um nó 'code' opaco, nunca visitado como 'text'
+  it('não transforma [[texto]] dentro de um bloco de código', () => {
+    const html = render('```mermaid\nflowchart TD\n  A[["algo<br/>outro"]]\n```')
+    expect(html).not.toContain('<a ')
+    expect(html).toContain('A[[')
+  })
+
+  it('falha quando um wiki link não aponta para um documento', () => {
+    expect(() => renderStrict('Veja [[arquivo-que-nao-existe]].')).toThrow('Broken wiki link')
+  })
+
+  it('aceita um wiki link que aponta para um documento do consumer', () => {
+    expect(renderStrict('Veja [[README]].')).toContain('href="/readme"')
+  })
+
+  it('mantém os formatos suportados sob validação estrita', () => {
+    expect(renderStrict('[[#Product]] [[README#Product]] [[README|início]]')).toContain('href="#product"')
+    expect(renderStrict('[[#Product]] [[README#Product]] [[README|início]]')).toContain('href="/readme#product"')
+  })
+
+  it('rejeita referências a arquivos que não são documentos', () => {
+    expect(() => renderStrict('Veja [[package.json]].')).toThrow('Broken wiki link')
+  })
+
+  it('rejeita referências que escapam da raiz do consumer', () => {
+    expect(() => renderStrict('Veja [[../package.json]].')).toThrow('Broken wiki link')
+  })
+
+  it('falha para uma referência wiki vazia ou sem fechamento', () => {
+    expect(() => renderStrict('Veja [[]].')).toThrow('Malformed wiki link')
+    expect(() => renderStrict('Veja [[sem fechamento.')).toThrow('Malformed wiki link')
+    expect(() => renderStrict('Veja [[README]] e [[sem fechamento.')).toThrow('Malformed wiki link')
+  })
+})

package/src/lib/remark-wiki-links.ts

@@ -0,0 +1,110 @@
+import { existsSync } from 'node:fs'
+import { resolve, sep } from 'node:path'
+import { visit } from 'unist-util-visit'
+import { PRODUCT_NAME } from './product-identity'
+
+interface MdastText {
+  type: 'text'
+  value: string
+}
+
+interface MdastLink {
+  type: 'link'
+  url: string
+  title: null
+  children: MdastText[]
+}
+
+interface MdastParent {
+  type: string
+  children: (MdastText | MdastLink | unknown)[]
+}
+
+interface WikiLinkOptions {
+  contentRoot?: string
+  failOnBrokenLinks?: boolean
+}
+
+function slugifyPath(ref: string): string {
+  return ref.toLowerCase().replace(/\s+/g, '-').replace(/[^\w/-]/g, '')
+}
+
+function slugifyHeading(heading: string): string {
+  return heading.toLowerCase().replace(/\s+/g, '-').replace(/[^\w-]/g, '')
+}
+
+// Constrói a URL a partir da referência crua entre colchetes: [[#heading]] vira
+// anchor local; [[page]] vira path; [[page#heading]] combina os dois — path e
+// heading são fatiados (slugify) separadamente pra não perder o separador "#".
+function buildUrl(ref: string): string {
+  if (ref.startsWith('#')) return '#' + slugifyHeading(ref.slice(1))
+  const hashIndex = ref.indexOf('#')
+  if (hashIndex >= 0) {
+    const pagePart = ref.slice(0, hashIndex)
+    const headingPart = ref.slice(hashIndex + 1)
+    return '/' + slugifyPath(pagePart) + '#' + slugifyHeading(headingPart)
+  }
+  return '/' + slugifyPath(ref)
+}
+
+function pagePartOf(ref: string): string {
+  const hashIndex = ref.indexOf('#')
+  return (hashIndex >= 0 ? ref.slice(0, hashIndex) : ref).replace(/^\/+/, '')
+}
+
+function wikiLinkResolves(ref: string, contentRoot: string): boolean {
+  const pagePart = pagePartOf(ref)
+  if (!pagePart) return true
+  const target = resolve(contentRoot, pagePart)
+  if (!target.startsWith(`${resolve(contentRoot)}${sep}`)) return false
+  if (/\.(?!mdx?$)[^/]+$/i.test(pagePart)) return false
+  const withoutExtension = target.replace(/\.mdx?$/i, '')
+  return [`${withoutExtension}.md`, `${withoutExtension}.mdx`, resolve(target, 'index.md'), resolve(target, 'index.mdx')]
+    .some(candidate => existsSync(candidate))
+}
+
+// Remark plugin: converts [[page]] / [[#heading]] / [[page#heading]] / [[page|label]]
+// Obsidian wiki links pra links markdown normais.
+export function remarkWikiLinks(options: WikiLinkOptions = {}) {
+  return (tree: MdastParent, file: { path?: string }) => {
+    visit(tree, 'text', (node: MdastText, index: number | undefined, parent: MdastParent | undefined) => {
+      if (!node.value.includes('[[')) return
+      const parts: (MdastText | MdastLink)[] = []
+      const pattern = /\[\[([^\]]+)\]\]/g
+      const openingMarkers = node.value.match(/\[\[/g)?.length ?? 0
+      const closingMarkers = node.value.match(/\]\]/g)?.length ?? 0
+      if (options.failOnBrokenLinks && openingMarkers !== closingMarkers) {
+        const source = file.path ? ` in ${file.path}` : ''
+        throw new Error(`[${PRODUCT_NAME}] Malformed wiki link${source}`)
+      }
+      let lastIndex = 0
+      let match: RegExpExecArray | null
+      while ((match = pattern.exec(node.value)) !== null) {
+        if (match.index > lastIndex) parts.push({ type: 'text', value: node.value.slice(lastIndex, match.index) })
+        const inner = match[1]
+        const pipeIdx = inner.indexOf('|')
+        const ref = pipeIdx >= 0 ? inner.slice(0, pipeIdx) : inner
+        const label = pipeIdx >= 0 ? inner.slice(pipeIdx + 1) : ref.replace(/^#/, '')
+        if (options.failOnBrokenLinks && options.contentRoot && !wikiLinkResolves(ref, options.contentRoot)) {
+          const source = file.path ? ` in ${file.path}` : ''
+          throw new Error(`[${PRODUCT_NAME}] Broken wiki link [[${inner}]]${source}`)
+        }
+        const url = buildUrl(ref)
+        parts.push({ type: 'link', url, title: null, children: [{ type: 'text', value: label }] })
+        lastIndex = match.index + match[0].length
+      }
+      if (!parts.length) {
+        if (options.failOnBrokenLinks && node.value.includes('[[')) {
+          const source = file.path ? ` in ${file.path}` : ''
+          throw new Error(`[${PRODUCT_NAME}] Malformed wiki link${source}`)
+        }
+        return
+      }
+      if (lastIndex < node.value.length) parts.push({ type: 'text', value: node.value.slice(lastIndex) })
+      if (parent && index !== undefined) {
+        parent.children.splice(index, 1, ...parts)
+        return index + parts.length
+      }
+    })
+  }
+}