diff --git a/README.md b/README.md index b246af5..42258c8 100644 --- a/README.md +++ b/README.md @@ -25,31 +25,37 @@ The static output is written to `build/` and can be served from any static host. The docs site is deployed on Vercel at [https://ghostmap-docs.vercel.app/](https://ghostmap-docs.vercel.app/). Vercel builds from this repository's default branch using the standard Docusaurus build (`npm run build`, output in `build/`); see `docusaurus.config.js` for site configuration. Publish the marketing site after a docs deploy completes, because the marketing site links to the rendered docs routes. +Subpage routing relies on `vercel.json` setting `cleanUrls: true` together with `trailingSlash: false` in `docusaurus.config.js`: Docusaurus emits `path/page.html` and Vercel serves it at `/path/page`. If subpages 404 in production while local `build/` contains the file, verify the Vercel project setting **Output Directory** is empty (so `vercel.json`'s `outputDirectory: "build"` applies) and that **Clean URLs** is enabled. + ## Content structure -| Folder | Purpose | +| Path | Purpose | |---|---| -| `docs/intro.md` | Landing page of the documentation. | -| `docs/get-started/` | Requisitos, instalación, primeros 5 minutos. | -| `docs/guide/` | Conceptos: symbols, anchors, ownership, validity gate, etc. | -| `docs/reference/` | Syntax, Ghost Tree, diagnostics, settings, rendimiento. | -| `docs/architecture/` | Arquitectura v1, loading policy, local state. | -| `docs/roadmap/` | Visión v2 (Ghost Index v2, Ghost Watcher, Ghost Comments, Ghost Threads, Ghost Graph). | -| `docs/status/` | Estado del proyecto y limitaciones conocidas. | -| `docs/changelog.md` | User-visible release notes. | +| `docs/intro.md` | Root start page (slug `/`). | +| `docs/overview.md` | Product overview (slug `/overview`). | +| `docs/install.md` | Install / access (slug `/install`). | +| `docs/vsix-install.md` | Detailed VSIX install reference. | +| `docs/get-started/` | Requirements and the first-5-minutes walkthrough. | +| `docs/guide/` | Concepts: symbols, anchors, ownership, validity gate. | +| `docs/reference/` | Syntax, Ghost Tree, diagnostics, settings, performance. | +| `docs/architecture/` | V1 pipeline, loading policy, local state. | +| `docs/roadmap/` | V2 vision. | +| `docs/status/` | Project status and known limits. | +| `docs/legal-support.md` | License summary and support contact (slug `/legal-support`). | | `docs/legal/` | Privacy Policy, Terms of Use, Third-Party Notices, Disclaimer. | +| `docs/changelog.md` | Release notes. | +| `docs/data-location.md`, `docs/troubleshooting.md`, `docs/faq.md`, `docs/glossary.md`, `docs/keyboard-shortcuts.md`, `docs/uninstall.md` | Standalone reference pages. | | `sidebars.js` | Sidebar layout. | | `docusaurus.config.js` | Site configuration. | +| `vercel.json` | Build and redirect config for Vercel. | ## Contributing to the docs -The docs are currently written in Spanish. The legal section and the changelog are in English (since they need to be canonical). A full English translation is on the roadmap. - To add a new page: -1. Create the `.md` file under the appropriate `docs//` folder with a YAML frontmatter block (`id`, `title`, `sidebar_label`). +1. Create the `.md` file under `docs/` (or the appropriate subfolder) with a YAML frontmatter block (`id`, `title`, `sidebar_label`, `slug`). 2. Add the page id to `sidebars.js` under the right category. -3. Run `npm start` to verify the page renders and links resolve. +3. Run `npm run build` to verify the page renders and links resolve. 4. Open a pull request. ## Related surfaces diff --git a/docs/architecture/arquitectura-v1.md b/docs/architecture/arquitectura-v1.md deleted file mode 100644 index 2a87faa..0000000 --- a/docs/architecture/arquitectura-v1.md +++ /dev/null @@ -1,59 +0,0 @@ ---- -id: arquitectura-v1 -title: Arquitectura actual (v1 / MVP) -sidebar_label: Arquitectura v1 ---- - -# Arquitectura actual (v1 / MVP) - -:::info -Esta sección es para devs curiosos y colaboradores. No es necesaria para el uso diario de GhostMap. -::: - -## Diagrama de flujo - -```text -Workspace - ↓ -Symbol Extraction (LSP → tree-sitter → regex/PHP fallback) - ↓ -Anchor Parsing (lee comentarios @ghost del documento) - ↓ -Ownership Resolution (pega metadata contextual al símbolo más cercano; - detecta detached/ambiguous) - ↓ -Hierarchy Builder (árbol por contención de rangos) - ↓ -Ghost Tree (filtros, búsqueda, iconos) - ↓ -VS Code UI (Tree View + Hover + Diagnostics + Code Actions) -``` - -## Cuándo se ejecuta - -Este pipeline completo se ejecuta: - -- Al abrir o activar un editor. -- En cada edición, con un pequeño retraso (debounce) para no recalcular en cada tecla. - -En V1, no hay persistencia completa entre sesiones a nivel de workspace — cada apertura de archivo repite el cálculo. La excepción es la caché de continuidad por documento descrita en [Local State](/architecture/local-state). El [roadmap v2](/roadmap/vision-v2) plantea eliminar este recálculo por completo con un índice persistente de workspace. - -## Modelo de datos (`GhostItem`) - -```ts -interface GhostItem { - id: string; - name: string; - type: 'function' | 'class' | 'anchor'; - range: vscode.Range; - endLine?: number; - anchorKind?: 'single' | 'range' | 'contextual'; - description?: string; - status?: string; - children?: GhostItem[]; -} -``` - -## Siguiente paso - -Continúa con **[Loading Policy](/architecture/loading-policy)** para entender cómo GhostMap maneja archivos grandes. diff --git a/docs/architecture/loading-policy.md b/docs/architecture/loading-policy.md index 05bdada..ed0ee90 100644 --- a/docs/architecture/loading-policy.md +++ b/docs/architecture/loading-policy.md @@ -1,30 +1,29 @@ --- id: loading-policy -title: Loading Policy (archivos grandes) +title: Loading Policy (large files) sidebar_label: Loading Policy --- -# Loading Policy (archivos grandes) +# Loading Policy (large files) -## Problema que resuelve +## The problem it solves -Sin límites, abrir un archivo enorme (decenas o cientos de miles de líneas) dispararía el pipeline completo de extracción y construcción del árbol en cada apertura o edición, lo que podría congelar la UI del editor. +Without limits, opening a huge file (tens or hundreds of thousands of lines) would fire the full extraction and tree-building pipeline on every open or edit, which could freeze the editor UI. -## Comportamiento +## Behavior -- Existe un presupuesto por defecto: `ghostmap.loading.maxAutoLines = 60000` (60,000 líneas). -- Si un archivo supera ese presupuesto, el **refresco automático** (al abrir o editar) se omite por defecto — no se ejecuta un análisis "fresco". -- Si existe un **snapshot previo válido** en el [Local State](/architecture/local-state), ese snapshot puede seguir mostrándose (UI "cacheada/stale") aunque no se recalcule. -- El **refresco manual** (botón `Refresh`) sobre un archivo que excede el presupuesto **también se omite por defecto**, a menos que habilites explícitamente `ghostmap.loading.allowManualLargeFileRefresh = true`. +- A default budget exists: `ghostmap.loading.maxAutoLines = 60000` (60,000 lines). +- If a file exceeds that budget, the **automatic refresh** (on open or edit) is skipped by default: no fresh analysis is run. +- If a **valid prior snapshot** exists in [Local State](/architecture/local-state), it can still be shown (cached/stale UI) even though no recompute happens. +- The **manual refresh** (`Refresh` button) on a file that exceeds the budget is **also skipped by default**, unless you explicitly enable `ghostmap.loading.allowManualLargeFileRefresh = true`. -## Qué verás si esto te afecta +## What you will see if this affects you -> "Este archivo tiene más de 60,000 líneas. GhostMap no recalculó el árbol automáticamente para evitar bloquear el editor. Si el árbol mostrado se ve desactualizado, puedes habilitar `ghostmap.loading.allowManualLargeFileRefresh` y usar `Refresh` manualmente." +> "This file has more than 60,000 lines. GhostMap did not recompute the tree automatically to avoid blocking the editor. If the displayed tree looks stale, you can enable `ghostmap.loading.allowManualLargeFileRefresh` and use `Refresh` manually." -:::tip Relación con v2 -El [Ghost Index v2](/roadmap/vision-v2) apunta a reducir este límite con un índice persistente y actualización incremental, para evitar recalcular archivos completos al abrirlos. Incluso en V2 seguirán haciendo falta presupuestos, backpressure y pruebas de recuperación para proteger el Extension Host en archivos extremos. -::: +> **Relation to v2:** +> The [Ghost Index v2](/roadmap/v2) aims to relax this limit with a persistent index and incremental updates, to avoid recomputing whole files on open. Even in V2, budgets, backpressure, and recovery tests will still be needed to protect the Extension Host on extreme files. -## Siguiente paso +## Next step -Continúa con **[Local State](/architecture/local-state)** para entender la caché de continuidad por workspace. +Continue with **[Local State](/architecture/local-state)** to understand the per-workspace continuity cache. diff --git a/docs/architecture/local-state.md b/docs/architecture/local-state.md index 14bf435..9718d99 100644 --- a/docs/architecture/local-state.md +++ b/docs/architecture/local-state.md @@ -6,18 +6,18 @@ sidebar_label: Local State # Local State (`.ghostmap/ghostmap.json`) -## Qué es +## What it is -Una caché local por workspace que GhostMap mantiene en V1, guardada en `.ghostmap/ghostmap.json` dentro del proyecto. GhostMap recuerda el estado de tus archivos entre sesiones para cargar más rápido. +A per-workspace local cache that GhostMap keeps in V1, stored in `.ghostmap/ghostmap.json` inside the project. GhostMap remembers the state of your files across sessions for faster loads. -Es un primer paso —más simple— hacia lo que el [roadmap v2](/roadmap/vision-v2) llama "Ghost Project Index": en V1 es una caché de continuidad por archivo/documento; en v2 se plantea como un índice completo de workspace con relaciones, watcher incremental y analítica. +It is a first (simpler) step toward what the [v2 roadmap](/roadmap/v2) calls the "Ghost Project Index": in V1 it is a per-file continuity cache; in v2 it becomes a full workspace index with relations, an incremental watcher, and analytics. -## Comportamiento +## Behavior -- Al cerrar y reabrir un documento, GhostMap puede restaurar el último estado conocido (`ghostmap.json`) en lugar de recalcular desde cero inmediatamente. -- **Regla de seguridad:** si los datos restaurados son "stale" (no se ha confirmado que sigan siendo válidos), no se publican como frescos en hover ni en navegación — la UI puede mostrar algo provisional, pero GhostMap no afirma que esa información está al día hasta confirmarlo. -- Casos manejados de forma defensiva: JSON corrupto y esquemas no soportados de versiones anteriores del archivo — en ambos casos, GhostMap no falla ni muestra datos incorrectos como válidos. +- On close and reopen of a document, GhostMap can restore the last known state (`ghostmap.json`) instead of recomputing from scratch immediately. +- **Safety rule:** if the restored data is "stale" (not yet confirmed valid), it is not published as fresh in hover or navigation. The UI may show a provisional view, but GhostMap does not claim that information is up to date until it confirms it. +- Defensively handled cases: corrupted JSON and unsupported schemas from older file versions. In both cases, GhostMap does not fail and does not show incorrect data as valid. -## Siguiente paso +## Next step -Con esto termina la sección de Arquitectura. Si quieres saber qué viene después, continúa con **[Roadmap — Visión v2](/roadmap/vision-v2)**. +This is the end of the Architecture section. If you want to know what comes next, continue with **[Roadmap: v2 vision](/roadmap/v2)**. diff --git a/docs/architecture/v1.md b/docs/architecture/v1.md new file mode 100644 index 0000000..85f69f9 --- /dev/null +++ b/docs/architecture/v1.md @@ -0,0 +1,58 @@ +--- +id: v1 +title: Current architecture (v1 / MVP) +sidebar_label: Architecture v1 +--- + +# Current architecture (v1 / MVP) + +> **Note:** +> This section is for curious devs and contributors. It is not required for daily GhostMap use. + +## Flow diagram + +```text +Workspace + ↓ +Symbol Extraction (LSP → Tree-sitter → regex/PHP fallback) + ↓ +Anchor Parsing (reads @ghost line comments in the document) + ↓ +Ownership Resolution (attaches contextual metadata to the closest symbol; + detects detached/ambiguous) + ↓ +Hierarchy Builder (tree by range containment) + ↓ +Ghost Tree (filters, search, icons) + ↓ +VS Code UI (Tree View + Hover + Diagnostics + Code Actions) +``` + +## When it runs + +The full pipeline runs: + +- When an editor opens or activates. +- On every edit, with a small debounce so it does not recompute on every keystroke. + +In V1, there is no full cross-session workspace persistence: each file open repeats the computation. The exception is the per-document continuity cache described in [Local State](/architecture/local-state). The [v2 roadmap](/roadmap/v2) plans to eliminate this recompute with a persistent workspace index. + +## Data model (`GhostItem`) + +```ts +interface GhostItem { + id: string; + name: string; + type: 'function' | 'class' | 'anchor'; + range: vscode.Range; + endLine?: number; + anchorKind?: 'single' | 'range' | 'contextual'; + description?: string; + status?: string; + children?: GhostItem[]; +} +``` + +## Next step + +Continue with **[Loading Policy](/architecture/loading-policy)** to understand how GhostMap handles large files. diff --git a/docs/changelog.md b/docs/changelog.md index 0e820ca..8e3c5e0 100644 --- a/docs/changelog.md +++ b/docs/changelog.md @@ -8,6 +8,8 @@ sidebar_label: Changelog Every user-visible fix and feature in GhostMap is logged here with the reasoning behind it. This is the product changelog; the round-by-round internal log lives alongside the extension source. +Public history starts at `0.5.0`, the first version stamp shipped outside the maintainers. Earlier work was internal stabilization and is summarized below. + ## 0.5.0 - June 18, 2026 The first version stamp after multiple rounds of stabilization. Marks GhostMap as feature-complete pre-1.0: the Ghost Tree, the Ghost Engine, the Ghost Index, anchors, diagnostics, and status badges all behave as documented. @@ -15,7 +17,7 @@ The first version stamp after multiple rounds of stabilization. Marks GhostMap a ### Added - **Status badges in the Ghost Tree header**: the panel title now shows `[loading]`, `[cached]`, `[stale-cache]`, `[skipped]`, `[no items]`, or `[discarded:...]` so you can see exactly what the engine is doing without opening the console. -- **Snippet coverage widened to 20 language IDs**: the `gh` / `gw` / `gr` / `gl` / `gxl` / `gxr` prefixes are now available in JavaScript, TypeScript, JSX, TSX, C, C++, C#, Java, Go, Rust, PHP, Kotlin, Swift, Scala, Groovy, Solidity, Python, Ruby, Elixir, and Shell. +- **Snippet coverage widened to 20 language IDs**: the `gh` / `gw` / `gr` / `gl` / `gxl` / `gxr` prefixes are now available in JavaScript, TypeScript, JSX, TSX, C, C++, C#, Java, Go, Rust, PHP, Kotlin, Swift, Scala, Groovy, Solidity, Python, Ruby, Elixir, and Shell. Snippet availability does not imply Ghost Tree symbol extraction support. ### Fixed (round 6) @@ -65,4 +67,4 @@ The first version stamp after multiple rounds of stabilization. Marks GhostMap a ## Next steps -For the V2 vision, see the [Roadmap](/roadmap/vision-v2). For known limitations of the current release, see the [Disclaimer](/legal/disclaimer). +For known limitations of the current release, see the [Disclaimer](/legal/disclaimer). diff --git a/docs/data-location.md b/docs/data-location.md index 5361c06..025374f 100644 --- a/docs/data-location.md +++ b/docs/data-location.md @@ -1,78 +1,78 @@ --- id: data-location -title: ¿Dónde guarda los datos GhostMap? -sidebar_label: Dónde están tus datos +title: Where does GhostMap store data? +sidebar_label: Where your data lives --- -# ¿Dónde guarda los datos GhostMap? +# Where does GhostMap store data? -Resumen corto: **todo se queda en tu máquina**. GhostMap no manda nada a ningún servidor. +Short answer: **everything stays on your machine**. GhostMap does not send anything to any server. -Esta página detalla qué guarda, dónde lo guarda y cómo limpiarlo si quieres empezar de cero. +This page details what it stores, where it stores it, and how to wipe it if you want to start fresh. -## El caché `.ghostmap/ghostmap.json` +## The `.ghostmap/ghostmap.json` cache -**Ubicación:** dentro de cada workspace abierto, en `.ghostmap/ghostmap.json`. +**Location:** inside each open workspace, at `.ghostmap/ghostmap.json`. -**Qué contiene:** snapshots de los árboles de símbolos y anchors de los archivos que has abierto en ese workspace. Cada entrada incluye: +**Contents:** snapshots of the symbol and anchor trees for the files you have opened in that workspace. Each entry includes: -- URI del archivo -- Lenguaje -- Cantidad de líneas y bytes -- Fingerprint SHA-256 del contenido (para detectar cambios) -- Lista de símbolos extraídos (clases, funciones, etc.) -- Jerarquía resuelta -- Lista de anchors `@ghost` parseados -- Momento de captura +- File URI +- Language +- Line and byte counts +- SHA-256 fingerprint of the content (to detect changes) +- Extracted symbol list (classes, functions, etc.) +- Resolved hierarchy +- Parsed `@ghost` anchor list +- Capture timestamp -**Tamaño máximo:** 2 MB por workspace. Cuando se llega al límite, las entradas más antiguas se eliminan primero (FIFO por `capturedAt`). +**Maximum size:** 2 MB per workspace. When the limit is hit, the oldest entries are removed first (FIFO by `capturedAt`). -**Formato:** JSON con `schemaVersion: 1`. +**Format:** JSON with `schemaVersion: 1`. -## Settings de VS Code +## VS Code settings -Los settings de `ghostmap.*` se guardan donde VS Code guarda cualquier setting: +`ghostmap.*` settings live where VS Code stores any setting: - **User settings:** `%APPDATA%\Code\User\settings.json` (Windows), `~/Library/Application Support/Code/User/settings.json` (macOS), `~/.config/Code/User/settings.json` (Linux). -- **Workspace settings:** `.vscode/settings.json` dentro del proyecto. +- **Workspace settings:** `.vscode/settings.json` inside the project. -GhostMap no escribe nunca settings automáticamente; tú decides cuándo cambiar uno. +GhostMap never writes settings automatically; you decide when to change one. -## El extension en sí +## The extension itself -VS Code instala las extensiones en: +VS Code installs extensions in: - **Windows:** `%USERPROFILE%\.vscode\extensions\ghostmap.ghostmap-` - **macOS / Linux:** `~/.vscode/extensions/ghostmap.ghostmap-` -Dentro de la carpeta del extension viven el código compilado, las gramáticas WASM y los snippets. GhostMap no toca esta carpeta en tiempo de ejecución salvo para leer recursos. +Inside the extension folder live the compiled code, the WASM grammars, and the snippets. GhostMap does not touch this folder at runtime except to read resources. -## Lo que GhostMap NUNCA guarda +## What GhostMap NEVER stores -- Ningún log local fuera de la consola de Output de VS Code (cuando activas `performanceLogging`). -- Ninguna telemetría. -- Ninguna identidad de usuario, máquina o sesión. -- Ningún historial de archivos abiertos fuera del snapshot persistente del workspace activo. +- No local log outside the VS Code Output console (when you enable `performanceLogging`). +- No telemetry. +- No user, machine, or session identity. +- No history of opened files outside the persistent snapshot for the active workspace. -## ¿Debo añadirlo a `.gitignore`? +## Should I add it to `.gitignore`? -**Sí, para evitar contaminar el repo con caché generada.** Añade a tu `.gitignore`: +**Yes, to avoid polluting the repo with generated cache.** Add to your `.gitignore`: ```text .ghostmap/ ``` -Razones: +Reasons: -1. El snapshot depende del estado de los archivos en tu disco. Cada developer del equipo lo regeneraría con su propio contenido. -2. El fingerprint SHA-256 invalida la mayor parte del caché cuando alguien hace pull, así que checkearlo no acelera nada en equipo. +1. The snapshot depends on the state of files on your disk. Every dev on the team would regenerate it with their own content. +2. The SHA-256 fingerprint invalidates most of the cache when someone pulls, so checking it in does not speed anything up for the team. -## Limpieza manual +## Manual cleanup -Si quieres forzar a GhostMap a recalcular desde cero todo lo que tienes en caché para un workspace: +If you want to force GhostMap to recompute everything cached for a workspace: ```bash -# Desde la raíz del workspace +# From the workspace root rm -rf .ghostmap/ ``` @@ -81,8 +81,8 @@ rm -rf .ghostmap/ Remove-Item -Recurse -Force .ghostmap\ ``` -GhostMap regenera el snapshot la próxima vez que abras un archivo en ese workspace. La primera apertura de cada archivo paga el costo completo de extracción; las siguientes vuelven a ser instantáneas. +GhostMap regenerates the snapshot the next time you open a file in that workspace. The first open of each file pays the full extraction cost; later opens are instant again. -## Limpieza global (desinstalación) +## Global cleanup (uninstall) -Si quieres remover GhostMap completamente de la máquina, ver **[Cómo desinstalar](/uninstall)**. +If you want to remove GhostMap completely from the machine, see **[How to uninstall](/uninstall)**. diff --git a/docs/faq.md b/docs/faq.md index d6a4f0c..335ea19 100644 --- a/docs/faq.md +++ b/docs/faq.md @@ -1,101 +1,101 @@ --- id: faq -title: Preguntas frecuentes +title: Frequently asked questions sidebar_label: FAQ --- -# Preguntas frecuentes +# Frequently asked questions -## ¿En qué se diferencia de la vista "Outline" de VS Code? +## How is this different from VS Code's "Outline" view? -La vista Outline nativa de VS Code muestra los símbolos del archivo activo según el language server, sin más. GhostMap añade: +The native Outline view shows the symbols of the active file from the language server, that is all. GhostMap adds: -- **Fallback automático** cuando el language server no responde o no está disponible, usando Tree-sitter y regex. En los **19 lenguajes soportados** (ver [Requisitos](/get-started/requisitos)) esto suele significar que tienes árbol incluso cuando Outline aparece vacío. En lenguajes fuera de esa lista (workstream de expansión planificado, ver [Disclaimer](/legal/disclaimer)), no hay árbol — GhostMap no inventa estructura. -- **Anotaciones `@ghost`** integradas al árbol: TODOs nombrados, regiones marcadas, descripciones con status, todo navegable. -- **Snapshot persistente por archivo** entre sesiones: abrir un archivo previamente visto pinta el árbol en < 50 ms, no hay que esperar al LSP. Hoy esa caché es por documento, no un índice de workspace completo — eso es V2 (ver [Roadmap](/roadmap/vision-v2)). -- **Scanner progresivo** para archivos de 60k líneas sin congelar el editor. -- **Diagnósticos** sobre tus anchors y quick fixes. +- **Automatic fallback** when the language server is not responding or not available, using Tree-sitter and regex. In the **19 supported languages** (see [Requirements](/get-started/requirements)) this usually means you still have a tree even when Outline is empty. In languages outside that list (planned expansion workstream, see [Disclaimer](/legal/disclaimer)) there is no tree: GhostMap does not invent structure. +- **`@ghost` annotations** woven into the tree: named TODOs, marked regions, descriptions with status, all navigable. +- **Per-file persistent snapshot** across sessions: opening a previously seen file paints the tree in < 50 ms; you do not have to wait for the LSP. Today that cache is per-document, not a full workspace index: that is V2 (see [Roadmap](/roadmap/v2)). +- **Progressive scanner** for files of 60k lines without freezing the editor. +- **Diagnostics** on your anchors plus quick fixes. -Outline sigue siendo útil para lenguajes donde el LSP es excelente y no necesitas anchors. GhostMap es la opción cuando trabajas en archivos grandes, cambias de lenguaje constantemente, o quieres dejar marcas estructuradas en el código. +Outline is still useful for languages where the LSP is excellent and you do not need anchors. GhostMap is the option when you work on large files, switch languages constantly, or want structured marks in your code. -## ¿Requiere instalar algo aparte del extension? +## Does it require anything besides the extension? -No. Las 19 gramáticas Tree-sitter vienen pre-compiladas dentro de la extensión, no se descargan en tiempo de ejecución. Si tienes un language server activo para tu lenguaje, GhostMap lo aprovechará automáticamente; si no, usa el fallback. Ver [Requisitos](/get-started/requisitos). +No. The 19 Tree-sitter grammars are pre-compiled inside the extension; they are not downloaded at runtime. If you have an active language server for your language, GhostMap will use it automatically; otherwise it uses the fallback. See [Requirements](/get-started/requirements). -## ¿Funciona sin conexión a internet? +## Does it work offline? -Sí. GhostMap no hace ninguna llamada de red. Toda la extracción de símbolos, parseo de anchors, persistencia y análisis sucede localmente. +Yes. GhostMap makes no network calls. All symbol extraction, anchor parsing, persistence, and analysis happens locally. -## ¿Manda datos a algún servidor? +## Does it send data to any server? -No. La extensión no envía datos de proyecto (código, contenido de archivos, rutas, telemetría ni metadata) a mantenedores ni a servidores de GhostMap. Para una copia de la Privacy Policy vigente, escribir a [getghostmap@proton.me](mailto:getghostmap@proton.me). +No. The extension does not send project data (code, file content, paths, telemetry, or metadata) to maintainers or to GhostMap servers. For a copy of the active Privacy Policy, write to [getghostmap@proton.me](mailto:getghostmap@proton.me). -## ¿Funciona en VS Code Web / vscode.dev? +## Does it work on VS Code Web / vscode.dev? -De forma limitada. GhostMap se declara como `extensionKind: ["workspace"]`, lo que significa que requiere un host de extensión completo. En entornos virtuales como vscode.dev, el Ghost Tree funciona en memoria pero la persistencia a `.ghostmap/ghostmap.json` no está disponible. +In a limited way. GhostMap declares itself as `extensionKind: ["workspace"]`, which means it requires a full extension host. In virtual environments like vscode.dev, the Ghost Tree works in memory but persistence to `.ghostmap/ghostmap.json` is not available. -## ¿Qué pasa con la carpeta `.ghostmap/`? +## What about the `.ghostmap/` folder? -Es el caché local que GhostMap mantiene por workspace. Contiene los árboles snapshot de los archivos que has abierto. Ver [¿Dónde guarda los datos GhostMap?](/data-location) para más detalle. +It is the local cache GhostMap keeps per workspace. It contains the snapshot trees for files you have opened. See [Where does GhostMap store data?](/data-location) for more detail. -**¿Debería commitearla?** No. Añádela a `.gitignore`: +**Should I commit it?** No. Add it to `.gitignore`: ```text .ghostmap/ ``` -**¿Es seguro borrarla?** Sí. La próxima apertura de cada archivo paga el costo de extracción completa una vez y se vuelve a poblar. +**Is it safe to delete?** Yes. The next open of each file pays the extraction cost once and the cache is repopulated. -## ¿Por qué los archivos > 60k líneas se marcan como `[skipped]`? +## Why are files > 60k lines flagged as `[skipped]`? -Para mantener el editor responsivo. El scanner regex evalúa un patrón por línea por lenguaje, y arriba de ~60k líneas el costo acumulado degrada la responsividad. Si necesitas analizar un archivo más grande: +To keep the editor responsive. The regex scanner evaluates one pattern per line per language, and above roughly 60k lines the accumulated cost degrades responsiveness. If you need to analyze a larger file: -- Sube `ghostmap.loading.maxAutoLines`. -- O activa `ghostmap.loading.allowManualLargeFileRefresh` y dispara el refresh manualmente con `GhostMap: Refresh`. +- Raise `ghostmap.loading.maxAutoLines`. +- Or enable `ghostmap.loading.allowManualLargeFileRefresh` and fire the refresh manually with `GhostMap: Refresh`. -Ver [Settings](/reference/settings). +See [Settings](/reference/settings). -## ¿Por qué hay tantos "tiers" de lenguajes? +## Why are there so many language "tiers"? -Algunos lenguajes tienen gramáticas que un scanner basado en regex y Tree-sitter cubre completamente (Tier 1). Otros tienen features que requerirían un parser específico real (Tier 2, Tier 3). El [Disclaimer](/legal/disclaimer) detalla los gaps conocidos por lenguaje. +Some languages have grammars that a regex- and Tree-sitter-based scanner covers fully (Tier 1). Others have features that would need a real specific parser (Tier 2, Tier 3). The [Disclaimer](/legal/disclaimer) details known gaps per language. -## ¿Cuánto ocupa la extensión? +## How big is the extension? -La descarga es de unos 35 MB, dominados por las 19 gramáticas Tree-sitter en formato WASM. En memoria activa el costo es bajo: solo las gramáticas de los lenguajes que has tocado en la sesión se cargan. +The download is about 35 MB, dominated by the 19 Tree-sitter grammars in WASM. Active memory cost is low: only the grammars for languages you have touched in the session are loaded. -## ¿GhostMap usa IA? +## Does GhostMap use AI? -No en V1. Toda la extracción es determinista (LSP / Tree-sitter / regex). La V2 contempla features asistidos por IA (explicaciones automáticas, sugerencias de Range Anchors) pero serán opcionales y se anunciarán explícitamente cuando lleguen. +Not in V1. All extraction is deterministic (LSP / Tree-sitter / regex). V2 contemplates AI-assisted features (automatic explanations, Range Anchor suggestions) but they will be optional and announced explicitly when they arrive. -## ¿Cómo creo un Anchor? +## How do I create an Anchor? -La forma más rápida es escribir `gh` y presionar Tab sobre la línea anterior a un símbolo. El snippet genera un Contextual Anchor que se adjunta al símbolo más cercano. Ver [Primeros 5 minutos](/get-started/primeros-5-minutos) y [Sintaxis](/reference/sintaxis). +The quickest way is to type `gh` and press Tab on the line above a symbol. The snippet generates a Contextual Anchor that attaches to the closest symbol. See [First 5 minutes](/get-started/first-5-minutes) and [Syntax](/reference/syntax). -## ¿Puedo poner `@ghost` en un comentario de bloque `/* */`? +## Can I put `@ghost` inside a block comment `/* */`? -No en V1. Solo se reconocen comentarios de línea (`//` o `#`). Ver [Sintaxis: solo comentarios de línea](/reference/sintaxis#solo-comentarios-de-línea). +Not in V1. Only line comments are recognized (`//` or `#`). See [Syntax: line comments only](/reference/syntax#line-comments-only). -## ¿Hay atajos de teclado por defecto? +## Are there default keyboard shortcuts? -Sí, uno: **Ctrl+Alt+G** (**Cmd+Alt+G** en macOS) ejecuta `GhostMap: Refresh` mientras el editor tiene foco. Ver [Atajos de teclado](/keyboard-shortcuts). +Yes, one: **Ctrl+Alt+G** (**Cmd+Alt+G** on macOS) runs `GhostMap: Refresh` while the editor has focus. See [Keyboard shortcuts](/keyboard-shortcuts). -## ¿Qué licencia tiene GhostMap V1? +## What license does GhostMap V1 use? -GhostMap V1 se publica como **source-available** bajo la **GhostMap Free Non-Commercial License**: el código es legible y se permite el uso personal, educativo y de evaluación/testing sin costo. El uso comercial, empresarial, en producción o que genere ingresos requiere autorización por escrito (o un futuro flujo de licencia comercial) — no está cubierto por esta licencia ni por donaciones. La visión Enterprise queda como roadmap futuro para integraciones de equipo; no es una funcionalidad disponible hoy. Ver los Términos de uso (incluidos en el repositorio como `LICENSE`; consultas a getghostmap@proton.me) y [Roadmap](/roadmap/vision-v2). +GhostMap V1 ships as **source-available** under the **GhostMap Free Non-Commercial License**: the code is readable and personal, educational, and evaluation/testing use is free. Commercial, business, production, or revenue-generating use requires written authorization (or a future commercial license flow). Donations do not grant commercial rights. The Enterprise vision is roadmap, not shipped today. See the Terms of Use (shipped as `LICENSE`; questions to getghostmap@proton.me) and the [Roadmap](/roadmap/v2). -## ¿Por qué no aparece GhostMap en VS Code Marketplace u Open VSX todavía? +## Why is GhostMap not on VS Code Marketplace or Open VSX yet? -Hoy GhostMap se instala por **VSIX local** construido desde el repo con `npx @vscode/vsce package`. GitHub Releases queda como canal planificado post-tag; todavía no hay release público. +Today GhostMap installs via a **local VSIX** built from the repo with `npx @vscode/vsce package`. GitHub Releases is a planned post-tag channel; there is no public release yet. -- **VS Code Marketplace — pendiente.** El paquete todavía no tiene `publisher` configurado en `package.json`; falta dar de alta el publisher en Marketplace y completar el primer `vsce publish`. Mientras tanto, instalar por VSIX es funcionalmente equivalente al Marketplace, solo que sin actualizaciones automáticas dentro del editor. -- **Open VSX — planificado.** Será el puente para usuarios de **VSCodium, Cursor, Gitpod** y demás editores que consumen Open VSX en vez del Marketplace de Microsoft. Pensado para publicarse antes o en paralelo con la aprobación en Marketplace. El script de publicación (`publish:open-vsx`, que invoca `ovsx publish`) ya está preparado en `package.json` del repo `genesis`; falta registrar el namespace en open-vsx.org, generar el token y ejecutar el primer publish. +- **VS Code Marketplace: pending.** The package does not have a `publisher` configured in `package.json` yet; the publisher has to be registered in Marketplace and the first `vsce publish` has to run. In the meantime, installing by VSIX is functionally equivalent to the Marketplace, just without automatic in-editor updates. +- **Open VSX: planned.** It will be the bridge for users of **VSCodium, Cursor, Gitpod**, and other editors that consume Open VSX instead of Microsoft's Marketplace. Planned to publish before or in parallel with Marketplace approval. The publish script (`publish:open-vsx`, calling `ovsx publish`) is already prepared in `package.json` of the `genesis` repo; namespace registration in open-vsx.org, the token, and the first publish are pending. -Mientras esos canales sean ⏳ pendientes / 🧭 planificados, la ruta oficial es la documentada en **[Instalación](/get-started/instalacion)** y **[Instalar desde VSIX](/vsix-install)**. +While those channels are pending / planned, the official path is in **[Install](/install)** and **[Install from VSIX](/vsix-install)**. -## ¿Cómo lo desinstalo? +## How do I uninstall it? -Ver [Cómo desinstalar](/uninstall). +See [How to uninstall](/uninstall). -## Siguiente paso +## Next step -Si tienes un problema específico, escríbenos a **getghostmap@proton.me** con los pasos para reproducirlo. +If you have a specific problem, write to **getghostmap@proton.me** with reproduction steps. diff --git a/docs/get-started/first-5-minutes.md b/docs/get-started/first-5-minutes.md new file mode 100644 index 0000000..8f119f6 --- /dev/null +++ b/docs/get-started/first-5-minutes.md @@ -0,0 +1,73 @@ +--- +id: first-5-minutes +title: First 5 minutes +sidebar_label: First 5 minutes +--- + +# First 5 minutes + +This guide takes you from zero to your first Ghost Tree, with no theory required up front. If you want to understand the *why* of each piece later, the [Guide](/guide/philosophy) section covers it. + +## Step 1: Open any file in your project + +The **GhostMap** panel shows up in the side bar. If the file has no annotations yet, the panel is empty. + +## Step 2: Type `gh` and press Tab above a function or class + +```ts +class PaymentService { + + gh (type "gh" and press Tab here) + charge(amount: number) { + // ... + } +} +``` + +GhostMap detects that `charge` is the closest symbol and autocompletes to: + +```ts +class PaymentService { + + // @ghost charge description: | status: todo + charge(amount: number) { + // ... + } +} +``` + +## Step 3: Fill in the description and save + +```ts + // @ghost charge description: validate negative amounts | status: todo + charge(amount: number) { +``` + +## Step 4: Look at the GhostMap panel + +```text +PaymentService +└── charge (todo): validate negative amounts +``` + +## Step 5: Create your first named Anchor + +An Anchor with `#name` does not need to be attached to any function. It is ideal for general notes about the file or the module: + +```ts +// @ghost #pending-payments description: review Stripe v2 integration | status: review +``` + +```text +PaymentService +└── charge (todo): validate negative amounts +pending-payments (review): review Stripe v2 integration +``` + +## Step 6: Filter + +Click the filter icon in the panel, pick `todo`, and the tree shows only the pending Ghosts. + +## That is all + +From here on, every `// @ghost ...` you write organizes itself. To understand the difference between the three annotation types (Point, Contextual, Range), continue with **[Guide / Philosophy](/guide/philosophy)** then **[Syntax reference](/reference/syntax)**. diff --git a/docs/get-started/instalacion.md b/docs/get-started/instalacion.md deleted file mode 100644 index bddc3c5..0000000 --- a/docs/get-started/instalacion.md +++ /dev/null @@ -1,65 +0,0 @@ ---- -id: instalacion -title: Instalación -sidebar_label: Instalación ---- - -# Instalación - -GhostMap es una extensión de Visual Studio Code. No necesitas configurar nada externo: ni servidores, ni cuentas, ni archivos de configuración antes de empezar. - -:::note -¿Tienes dudas sobre si GhostMap funcionará en tu máquina o con archivos muy grandes? Consulta [Requisitos mínimos](/get-started/requisitos) antes de instalar. -::: - -## Estado de distribución - -| Canal | Estado actual | Notas | -| --- | --- | --- | -| **VSIX por contacto directo** | ✅ Disponible | Camino único hoy. Escribí a [getghostmap@proton.me](mailto:getghostmap@proton.me) y te enviamos el paquete `ghostmap-0.5.0.vsix`. Ver [Instalar desde VSIX](/vsix-install). | -| **Compilar el VSIX desde el código fuente** | 🔒 Solo con acceso al repo | El repositorio `genesis` es privado. Si te otorgaron acceso, podés empaquetar localmente con `npx @vscode/vsce package`. No es un camino de auto-servicio público. | -| **VSIX desde GitHub Releases** | 🧭 Planificado post-tag | El repo público aún no está abierto. Los releases futuros podrán adjuntar el VSIX después de crear un tag. | -| **VS Code Marketplace** | ⏳ Preparado, no publicado | El paquete todavía no tiene `publisher` configurado en `package.json`; falta dar de alta al publisher en Marketplace y completar el primer `vsce publish`. Mientras tanto, no hay listado oficial. | -| **Open VSX** (VSCodium, Cursor y otros consumidores de Open VSX) | ⏳ Preparado, no publicado | Será el puente para editores compatibles con Open VSX antes o en paralelo con la aprobación en Marketplace. El script de publicación (`publish:open-vsx`, que invoca `ovsx publish`) ya está preparado en `package.json`; quedan pendientes registrar el namespace en open-vsx.org, generar el token de publicación y ejecutar el primer publish. | - -Hasta que Marketplace y Open VSX estén publicados, el camino oficial es el VSIX enviado por contacto directo. GitHub Releases será el canal post-tag cuando el repo público esté abierto. - -## Editor - -- Visual Studio Code (versión reciente, 1.85 o superior — ver [Requisitos](/get-started/requisitos)). -- Un proyecto en alguno de los 19 lenguajes soportados: JavaScript, TypeScript, JSX, TSX, Python, PHP, Java, C#, Go, Rust, C, C++, Ruby, Dart, Elixir, Groovy, Julia, Objective-C, Scala o Solidity. - -Si tu lenguaje no tiene un *language server* activo, GhostMap usa automáticamente el mejor respaldo local disponible. En lenguajes Tier 1 suele conservar buen detalle; en Tier 2 o Tier 3 puede producir un árbol más parcial. Consulta [Requisitos mínimos](/get-started/requisitos#matriz-de-calidad-por-lenguaje) antes de tratar el resultado como fuente única de verdad. - -## Pasos (camino actual — VSIX por contacto directo) - -1. Escribí a [getghostmap@proton.me](mailto:getghostmap@proton.me) pidiendo el VSIX. Te respondemos con el archivo `ghostmap-0.5.0.vsix`. Más detalle en **[Instalar desde un archivo VSIX](/vsix-install)**. -2. Abre VS Code. -3. Ve a la pestaña **Extensions** (`Ctrl+Shift+X` / `Cmd+Shift+X`). -4. Menú **"..."** arriba a la derecha → **Install from VSIX...** → selecciona el `.vsix` recibido. -5. Recarga VS Code cuando te lo pida. - -:::note -El repositorio `genesis` (código fuente) es privado. Clonarlo y empaquetar localmente solo es posible si te otorgaron acceso explícito; no es un camino de auto-servicio. -::: - -Alternativa por línea de comandos: - -```bash -code --install-extension ghostmap-0.5.0.vsix -``` - -## Cuando Marketplace y Open VSX estén publicados - -Estos pasos quedan documentados para usarse cuando los canales correspondientes se marquen como ✅ arriba. Hoy ambos están preparados pero no publicados: - -- **VS Code Marketplace** (preparado, no publicado): abrir Extensions, buscar **GhostMap**, click en Install. El listado todavía no existe; no hay un enlace de Marketplace estable que recomendar. -- **Open VSX** (preparado, no publicado): instalación equivalente en VSCodium / Cursor / Gitpod y demás clientes de Open VSX. El paquete aparecerá listado en `open-vsx.org` cuando el primer `ovsx publish` se ejecute. - -## Verifica que quedó instalada - -Abre cualquier archivo de código en un lenguaje soportado. En la barra lateral de VS Code debería aparecer un nuevo panel llamado **GhostMap** (icono de fantasma). Si el archivo todavía no tiene anotaciones `@ghost`, el panel se mostrará vacío — es el comportamiento esperado. - -## Siguiente paso - -Continúa con **[Primeros 5 minutos](/get-started/primeros-5-minutos)** para escribir tu primer `@ghost` y ver el árbol en acción. diff --git a/docs/get-started/primeros-5-minutos.md b/docs/get-started/primeros-5-minutos.md deleted file mode 100644 index 651ba4e..0000000 --- a/docs/get-started/primeros-5-minutos.md +++ /dev/null @@ -1,73 +0,0 @@ ---- -id: primeros-5-minutos -title: Primeros 5 minutos -sidebar_label: Primeros 5 minutos ---- - -# Primeros 5 minutos - -Esta guía te lleva de cero a tu primer Ghost Tree funcionando, sin teoría previa. Si después quieres entender el *por qué* de cada pieza, la sección [Guía / Conceptos](/guide/philosophy) lo cubre en detalle. - -## Paso 1 — Abre cualquier archivo de tu proyecto - -El panel **GhostMap** aparece en la barra lateral. Si el archivo no tiene anotaciones todavía, el panel se ve vacío. - -## Paso 2 — Escribe `gh` y presiona Tab encima de una función o clase - -```ts -class PaymentService { - - gh␣ ← (escribe "gh" y presiona Tab aquí) - charge(amount: number) { - // ... - } -} -``` - -GhostMap detecta que `charge` es el símbolo más cercano y autocompleta: - -```ts -class PaymentService { - - // @ghost charge description: | status: todo - charge(amount: number) { - // ... - } -} -``` - -## Paso 3 — Completa la descripción y guarda - -```ts - // @ghost charge description: falta validar montos negativos | status: todo - charge(amount: number) { -``` - -## Paso 4 — Mira el panel GhostMap - -```text -PaymentService -└── charge (todo) — falta validar montos negativos -``` - -## Paso 5 — Crea tu primer Anchor con nombre propio - -Un Anchor con `#nombre` no necesita estar atado a ninguna función — es ideal para notas generales del archivo o del módulo: - -```ts -// @ghost #pendientes-pagos description: revisar integración con Stripe v2 | status: review -``` - -```text -PaymentService -└── charge (todo) — falta validar montos negativos -pendientes-pagos (review) — revisar integración con Stripe v2 -``` - -## Paso 6 — Filtra - -Haz clic en el ícono de filtro del panel → elige `todo` → solo verás los Ghosts pendientes en todo el proyecto. - -## Eso es todo - -A partir de aquí, cada `// @ghost ...` que escribas se organiza solo. Para entender las diferencias entre los tres tipos de anotación (Point, Contextual, Range), continúa con **[Guía / Conceptos](/guide/philosophy)** → **[Referencia de sintaxis](/reference/sintaxis)**. diff --git a/docs/get-started/requirements.md b/docs/get-started/requirements.md new file mode 100644 index 0000000..d777776 --- /dev/null +++ b/docs/get-started/requirements.md @@ -0,0 +1,73 @@ +--- +id: requirements +title: Requirements +sidebar_label: Requirements +--- + +# Requirements + +GhostMap is a VS Code extension. There is no server, no external account, and no system dependency outside the editor. + +## Editor + +| Requirement | Value | +|---|---| +| Visual Studio Code | **1.85 or newer** (declared in `engines.vscode`). VS Code will warn you if your version is older. | +| Operating system | Windows, macOS, Linux. Any platform where VS Code runs. | + +GhostMap targets **VS Code Desktop**. VS Code Web (`vscode.dev` / `github.dev`) and remote setups can restrict the filesystem, the Extension Host, or installable extensions. They are not a verified surface in V1. If you use Remote SSH, Dev Containers, WSL, or Codespaces, validate the behavior in your environment before depending on GhostMap for critical work. + +> **Note:** +> GhostMap was developed and tested mainly on Windows. File paths use `path.sep` for cross-platform compatibility, but macOS and Linux have not been exhaustively verified in V1. If you hit a platform-specific problem, write to [getghostmap@proton.me](mailto:getghostmap@proton.me). + +## Project language + +You do not need to install anything else just to use GhostMap. The extension ships: + +- **19 Tree-sitter grammars compiled to WASM**, packed inside the extension. Nothing is downloaded at runtime. +- **Regex fallback** that works with no external dependency. + +The only optional dependency that improves tree quality is an active **language server (LSP)** for your language. GhostMap uses it automatically when available; otherwise it drops to the next extraction layer on its own. + +## Language quality matrix + +| Tier | What to expect | Languages | +|---|---|---| +| **Tier 1: first-class** | Full symbol extraction and nesting on the current fixtures. Recommended tier to evaluate GhostMap. | TypeScript, TSX, JavaScript, JSX, Python, Rust, C#, Java, C++, C, PHP, Ruby, Dart | +| **Tier 2: best-effort** | Top-level symbols are available; nesting or some constructs may be partial depending on the file. | Go, Groovy, Objective-C | +| **Tier 3: top-level only** | Coarse index useful for orientation; deep nesting should not be assumed reliable. | Scala, Solidity, Julia, Elixir | + +If your language is Tier 2 or Tier 3, the fallback still tries to give you a useful tree, but the expected precision is lower than Tier 1. For critical flows, verify the result against the file before treating it as the single source of truth. + +> **Language expansion (separate workstream):** +> Roughly 20 additional languages are planned (Kotlin, Swift, Haskell, OCaml, Lua, R, Bash, the SQL family, and others). They are a separate workstream, blocked by: +> +> - reproducible packaging and provenance for Tree-sitter grammars and WASM, +> - query validity against the exact grammar version we ship or fork, +> - fixture coverage per language in `test/matrix/`, +> - and, in some cases, upstream PRs to the grammars themselves. +> +> These languages are **not** announced as supported until they pass that gate. If you open an item in one of them, GhostMap behaves as it does for an unknown language (no symbol tree appears). See [Disclaimer](/legal/disclaimer). + +## RAM and CPU + +GhostMap does not document a strict minimum RAM requirement. Some behaviors to keep in mind on low-memory machines: + +- With **80 to 90 percent RAM in use**, a language server can take 5 to 30 seconds to start. GhostMap waits up to 800 ms and then drops to the fallback automatically. The tree still appears, but with less detail than the LSP would give. +- In those conditions the **Ghost Index** is especially useful: instead of waiting for the LSP on every open, the tree loads from the local snapshot in under 50 ms. + +## Very large projects + +GhostMap analyzes files, not whole workspaces. For very large files there are automatic limits: + +| Limit | Default value | Setting to adjust it | +|---|---|---| +| Lines per file (auto-refresh) | 60,000 lines | `ghostmap.loading.maxAutoLines` | +| Size per file (auto-refresh) | 10 MB | `ghostmap.loading.maxAutoBytes` | +| "Tiny" files (no backpressure) | 50 lines or fewer | `ghostmap.loading.tinyLineThreshold` | + +If you regularly work with files that exceed those limits, raise them in `settings.json`. See [Settings](/reference/settings) and [Loading Policy](/architecture/loading-policy) for the detail. + +## Quick summary + +If VS Code 1.85 or newer runs on your machine, GhostMap runs on your machine. Performance limits show up on very large files or under extreme RAM pressure, not in normal use. diff --git a/docs/get-started/requisitos.md b/docs/get-started/requisitos.md deleted file mode 100644 index c97426f..0000000 --- a/docs/get-started/requisitos.md +++ /dev/null @@ -1,75 +0,0 @@ ---- -id: requisitos -title: Requisitos mínimos -sidebar_label: Requisitos mínimos ---- - -# Requisitos mínimos - -GhostMap es una extensión de VS Code. No requiere configuración de servidor, cuenta externa, ni dependencias del sistema fuera del editor. - -## Editor - -| Requisito | Valor | -|---|---| -| Visual Studio Code | **1.85 o superior** (declarado en `engines.vscode` del manifiesto). VS Code te avisará si tu versión es anterior. | -| Sistema operativo | Windows, macOS, Linux. Cualquier plataforma donde corra VS Code. | - -GhostMap está pensado para **VS Code Desktop**. VS Code Web (`vscode.dev` / `github.dev`) y entornos remotos pueden restringir el filesystem, el Extension Host o las extensiones instaladas; en V1 no se documentan como superficie verificada. Si usas Remote SSH, Dev Containers, WSL o Codespaces, valida el comportamiento en tu entorno antes de depender de GhostMap para trabajo crítico. - -:::note -GhostMap fue desarrollado y probado principalmente en Windows. Las rutas de archivos usan `path.sep` para compatibilidad cross-platform, pero macOS y Linux no han sido verificados de forma exhaustiva en V1. Si encuentras un problema específico de plataforma, escríbenos a [getghostmap@proton.me](mailto:getghostmap@proton.me). -::: - -## Lenguaje del proyecto - -No necesitas instalar nada extra solo para usar GhostMap. La extensión incluye: - -- **19 gramáticas Tree-sitter compiladas a WASM**, empaquetadas dentro de la extensión. No se descargan en tiempo de ejecución. -- **Regex fallback**, que funciona sin ninguna dependencia externa. - -La única dependencia opcional que mejora la calidad del árbol es tener activo un **language server (LSP)** para tu lenguaje. GhostMap lo usa automáticamente si está disponible; si no lo está, cae al siguiente nivel de extracción sin que tengas que hacer nada. - -## Matriz de calidad por lenguaje - -| Tier | Qué puedes esperar | Lenguajes | -|---|---|---| -| **Tier 1 — first-class** | Extracción de símbolos y nesting completo en los fixtures actuales. Es el nivel recomendado para evaluar GhostMap. | TypeScript, TSX, JavaScript, JSX, Python, Rust, C#, Java, C++, C, PHP, Ruby, Dart | -| **Tier 2 — best-effort** | Símbolos principales disponibles; el nesting o algunos constructos pueden ser parciales según el archivo. | Go, Groovy, Objective-C | -| **Tier 3 — top-level only** | Índice grueso útil para orientación básica; el nesting profundo no debe asumirse como confiable. | Scala, Solidity, Julia, Elixir | - -Si tu lenguaje cae en Tier 2 o Tier 3, el fallback sigue intentando darte un árbol útil, pero la precisión esperada es menor que en Tier 1. Para flujos críticos, verifica el resultado contra el archivo antes de usarlo como fuente única de verdad. - -:::note Expansión de lenguajes — workstream separado -Hay aproximadamente 20 lenguajes adicionales planificados (Kotlin, Swift, Haskell, OCaml, Lua, R, Bash, familia SQL, …). Son un workstream aparte, bloqueado por: - -- empaquetado de las gramáticas Tree-sitter y procedencia reproducible de los WASM, -- validez de los queries que escribimos o forkeamos contra la versión exacta de la gramática, -- cobertura de fixtures por lenguaje en `test/matrix/`, -- y, en algunos casos, PRs upstream a las propias gramáticas. - -Esos lenguajes **no** se anuncian como soportados hasta cumplir ese gate. Si el ítem que abres está en uno de ellos, GhostMap se comportará igual que en un lenguaje desconocido (no aparecerá árbol de símbolos). Ver [Disclaimer](/legal/disclaimer). -::: - -## RAM y CPU - -GhostMap no tiene un requisito de RAM mínima documentado. Sin embargo, hay comportamientos a tener en cuenta en entornos con poca memoria: - -- Con **80–90% de RAM en uso**, el arranque de un language server puede tardar entre 5 y 30 segundos. GhostMap espera hasta 800 ms y luego cae al fallback automáticamente. El árbol sigue apareciendo, pero sin el detalle que daría el LSP. -- En esas condiciones, el **Ghost Index** es especialmente útil: en lugar de esperar al LSP en cada apertura, el árbol carga desde el snapshot local en menos de 50 ms. - -## Proyectos muy grandes - -GhostMap analiza archivos, no workspaces completos. Para archivos muy grandes hay límites automáticos: - -| Límite | Valor por defecto | Setting para ajustarlo | -|---|---|---| -| Líneas por archivo (auto-refresh) | 60,000 líneas | `ghostmap.loading.maxAutoLines` | -| Tamaño por archivo (auto-refresh) | 10 MB | `ghostmap.loading.maxAutoBytes` | -| Archivos "tiny" (sin backpressure) | ≤ 50 líneas | `ghostmap.loading.tinyLineThreshold` | - -Si trabajas habitualmente con archivos que superan estos límites, puedes subirlos en `settings.json`. Consulta [Settings](/reference/settings) y [Loading Policy](/architecture/loading-policy) para el detalle. - -## Resumen rápido - -Si VS Code 1.85 o superior corre en tu máquina, GhostMap corre en tu máquina. Los límites de rendimiento aparecen con archivos muy grandes o bajo presión de RAM extrema, no en uso normal. diff --git a/docs/glossary.md b/docs/glossary.md index 8ffb697..1ec4aab 100644 --- a/docs/glossary.md +++ b/docs/glossary.md @@ -1,133 +1,133 @@ --- id: glossary -title: Glosario -sidebar_label: Glosario +title: Glossary +sidebar_label: Glossary --- -# Glosario +# Glossary -Términos que aparecen en la documentación y en la UI de GhostMap, definidos en un solo lugar. +Terms used in the documentation and in the GhostMap UI, defined in one place. ## Anchor -Una anotación `@ghost` escrita dentro de un comentario de línea del código. Hay tres tipos: [Point](/guide/semantic-anchor) (con `#nombre`), [Contextual](/guide/contextual-anchor) (sin `#nombre`, se adjunta al símbolo cercano) y [Range](/guide/range-anchor) (delimitada con `start` y `end`). +A `@ghost` annotation written inside a line comment. There are three types: [Point](/guide/semantic-anchor) (with `#name`), [Contextual](/guide/contextual-anchor) (no `#name`, attaches to the nearby symbol), and [Range](/guide/range-anchor) (bounded by `start` and `end`). ## Backpressure -Mecanismo del scheduler de GhostMap que retrasa el inicio de un refresh por 200 ms cuando detecta cambios rápidos de tab (menos de 150 ms entre ellos). Evita encolar análisis de archivos por los que el usuario solo pasó. Archivos pequeños lo saltan automáticamente. Ver [Rendimiento](/reference/rendimiento#tab-switching). +GhostMap's scheduler mechanism that delays the start of a refresh by 200 ms when it detects fast tab switches (less than 150 ms between them). It avoids queueing analyses for files the user just passed through. Small files skip it automatically. See [Performance](/reference/performance#tab-switching). ## Coalescer -Componente del scanner progresivo que agrupa varias publicaciones de batches en una sola actualización del árbol cada 250 ms. Evita que el panel parpadee durante el análisis de archivos grandes. +Progressive scanner component that groups several batch publications into a single tree update every 250 ms. Prevents panel flicker during the analysis of large files. ## Contextual Anchor -Anchor sin `#nombre`. Se adjunta automáticamente al símbolo más cercano dentro del [ownership radius](/guide/ownership-radius). Ver [Contextual Anchor](/guide/contextual-anchor). +Anchor without `#name`. Attaches automatically to the closest symbol within the [ownership radius](/guide/ownership-radius). See [Contextual Anchor](/guide/contextual-anchor). ## Generation -Identificador interno que se incrementa con cada refresh solicitado. GhostMap usa la generation para descartar trabajo cuyo resultado ya está obsoleto (por ejemplo, refresh del archivo A cuando el usuario ya cambió al archivo B). +Internal identifier that increments with every refresh request. GhostMap uses the generation to discard work whose result is already obsolete (for example, a refresh of file A when the user has already switched to file B). ## Ghost Comments -Nombre canónico de la futura forma "invisible" de los anchors en V2. La información Ghost dejará de vivir como texto en el comentario y se mostrará vía decoraciones y CodeLens, mientras el código fuente permanece limpio. Ver [Roadmap](/roadmap/vision-v2). +Canonical name for the future "invisible" form of anchors in V2. Ghost information will stop living as text in the comment and will be shown via decorations and CodeLens, while the source stays clean. See [Roadmap](/roadmap/v2). ## Ghost Context Graph -Nombre largo del **Ghost Graph**, el grafo de relaciones entre archivos, símbolos y dependencias que vivirá en el Ghost Index v2. +Long name for **Ghost Graph**: the graph of relations between files, symbols, and dependencies that will live in the Ghost Index v2. ## Ghost Engine -Nombre canónico de la pila de extracción de símbolos. Tres capas en orden: LSP (language server) → Tree-sitter WASM → regex fallback. Ver [Rendimiento](/reference/rendimiento#el-ghost-engine). +Canonical name for the symbol-extraction stack. Three layers in order: LSP (language server) then Tree-sitter WASM then regex fallback. See [Performance](/reference/performance#the-ghost-engine). ## Ghost Graph -Forma corta de "Ghost Context Graph". Visualización de las relaciones que vive en el Ghost Index v2. Ver [Roadmap](/roadmap/vision-v2). +Short form of "Ghost Context Graph". Visualization of the relations stored in the Ghost Index v2. See [Roadmap](/roadmap/v2). ## Ghost Index -Caché persistente que GhostMap mantiene por workspace en `.ghostmap/ghostmap.json`. En V1 es per-document. En V2 será per-workspace (Ghost Index v2). Ver [Local State](/architecture/local-state). +Persistent cache GhostMap keeps per workspace in `.ghostmap/ghostmap.json`. In V1 it is per-document. In V2 it will be per-workspace (Ghost Index v2). See [Local State](/architecture/local-state). ## Ghost Project Index -Sinónimo de **Ghost Index v2**. El índice persistente a nivel de workspace que reemplazará la caché por archivo de V1. +Synonym for **Ghost Index v2**: the persistent workspace-level index that will replace the per-file cache of V1. ## Ghost Threads -Nombre canónico de las discusiones por bloque de código planeadas para V2 Enterprise. Cada función, clase o range puede tener su propio hilo, con asignación de roles y puente con Slack. +Canonical name for the per-code-block discussions planned for V2 Enterprise. Every function, class, or range can have its own thread, with role assignment and a bridge to Slack. ## Ghost Tree -El árbol que GhostMap muestra en el panel lateral: clases, interfaces, funciones, métodos, anchors. Construido a partir de la salida del [Ghost Engine](#ghost-engine). +The tree GhostMap shows in the side panel: classes, interfaces, functions, methods, anchors. Built from the [Ghost Engine](#ghost-engine) output. ## Ghost Watcher -Componente planeado para V2: observador de archivos que mantiene el [Ghost Index v2](#ghost-index) actualizado de forma incremental cuando hay creación, eliminación, renombrado o modificación. +Component planned for V2: filesystem watcher that keeps the [Ghost Index v2](#ghost-index) incrementally up to date on create, delete, rename, or modify. ## Language ID -Identificador interno de VS Code para el lenguaje del archivo activo. Aparece en la barra de estado, esquina inferior derecha. Lo usa GhostMap para decidir qué patrones de extracción aplicar. +VS Code's internal identifier for the language of the active file. It appears in the status bar, lower right corner. GhostMap uses it to decide which extraction patterns apply. ## LSP -Language Server Protocol. Especificación que usan los language servers (TypeScript Server, Pyright, etc.) para exponer información del código. GhostMap consulta al LSP del lenguaje activo como primera capa del Ghost Engine. +Language Server Protocol. The spec language servers (TypeScript Server, Pyright, etc.) use to expose code information. GhostMap queries the active language's LSP as the first layer of the Ghost Engine. ## Ownership Radius -Cantidad de líneas alrededor de un [Contextual Anchor](#contextual-anchor) en las que GhostMap busca un símbolo al cual adjuntar la metadata. Default: 5. Configurable vía `ghostmap.ownershipRadius`. Ver [Ownership Radius](/guide/ownership-radius). +Number of lines around a [Contextual Anchor](#contextual-anchor) where GhostMap looks for a symbol to attach the metadata to. Default: 5. Configurable via `ghostmap.ownershipRadius`. See [Ownership Radius](/guide/ownership-radius). ## Point Anchor -Anchor con `#nombre` pero sin `start`/`end`. Crea su propio nodo en el árbol con identidad propia. También llamado **Semantic Anchor**. Ver [Semantic Anchor](/guide/semantic-anchor). +Anchor with `#name` but no `start`/`end`. Creates its own node in the tree with its own identity. Also called **Semantic Anchor**. See [Semantic Anchor](/guide/semantic-anchor). ## Progressive Scanner -Motor de extracción para archivos grandes. Procesa el archivo en batches de 4,000 líneas y publica los primeros 50 símbolos antes de terminar. Cede el control al event loop entre batches con `setImmediate` para que el editor siga responsivo. Ver [Rendimiento](/reference/rendimiento#el-scanner-progresivo-archivos-grandes). +Extraction engine for large files. Processes the file in 4,000-line batches and publishes the first 50 symbols before finishing. Yields control to the event loop between batches via `setImmediate` so the editor stays responsive. See [Performance](/reference/performance#the-progressive-scanner-large-files). ## Range Anchor -Anchor con `#nombre start ... end` que delimita una sección de código. Crea un nodo en el árbol que contiene todos los símbolos dentro de la región. Ver [Range Anchor](/guide/range-anchor). +Anchor with `#name start ... end` that bounds a section of code. Creates a node in the tree containing all symbols inside the region. See [Range Anchor](/guide/range-anchor). ## Refresh -Operación que recalcula el árbol para el documento activo. Puede ser disparada por un cambio de tab, una edición del archivo, o el comando manual `GhostMap: Refresh`. +Operation that recomputes the tree for the active document. Triggered by a tab switch, a file edit, or the manual `GhostMap: Refresh` command. ## Scheduler -Componente que gestiona la cola de refreshes. Mantiene como máximo uno en vuelo y uno encolado por archivo. Spam clicks colapsan al "último". Ver [Arquitectura](/architecture/arquitectura-v1). +Component that manages the refresh queue. Keeps at most one in-flight and one queued per file. Spam clicks collapse to the "last". See [Architecture](/architecture/v1). ## Semantic Anchor -Otro nombre para el [Point Anchor](#point-anchor) (anchor con `#nombre`). Llamado "semántico" porque tiene identidad propia y es referenciable como nodo del árbol. +Another name for [Point Anchor](#point-anchor) (anchor with `#name`). Called "semantic" because it has its own identity and is referenceable as a tree node. ## Snapshot -Una entrada del [Ghost Index](#ghost-index) que captura el estado de extracción de un archivo: árbol, anchors, fingerprint del contenido, momento de captura. Ver [Local State](/architecture/local-state). +A [Ghost Index](#ghost-index) entry that captures the extraction state of a file: tree, anchors, content fingerprint, capture timestamp. See [Local State](/architecture/local-state). ## Stale-cache -Estado en el que GhostMap está mostrando un snapshot previo (badge `[cached]`) mientras valida o re-extrae el archivo. Si el fingerprint no coincide, pasa a `[stale-cache]`. Resuelve solo cuando el refresh fresco completa. +State in which GhostMap is showing a prior snapshot (badge `[cached]`) while validating or re-extracting the file. If the fingerprint does not match, it switches to `[stale-cache]`. Resolves only when the fresh refresh completes. ## Status badge -El indicador entre corchetes que aparece en el título del panel GhostMap: `[loading]`, `[cached]`, `[stale-cache]`, `[skipped]`, `[no items]`, `[deferred]`, `[discarded:...]`. Te dice exactamente en qué estado está la extracción. +Bracketed indicator in the GhostMap panel title: `[loading]`, `[cached]`, `[stale-cache]`, `[skipped]`, `[no items]`, `[deferred]`, `[discarded:...]`. Tells you exactly what state extraction is in. ## Symbol -Clase, interfaz, struct, enum, método, función, constructor o anchor que aparece como nodo del Ghost Tree. Lo que cuenta como Symbol se decide en el [Symbol Validity Gate](/guide/symbol-validity-gate). +Class, interface, struct, enum, method, function, constructor, or anchor that shows up as a node in the Ghost Tree. What counts as a Symbol is decided by the [Symbol Validity Gate](/guide/symbol-validity-gate). ## Symbol Validity Gate -Filtro que decide qué identificadores se aceptan como Symbol. Rechaza nombres de una sola letra, palabras reservadas del lenguaje, y patrones ruidosos (`fn`, `cb`, `id`...). Ver [Symbol Validity Gate](/guide/symbol-validity-gate). +Filter that decides which identifiers are accepted as a Symbol. Rejects 1 to 2 letter names, language reserved words, and noisy patterns (`fn`, `cb`, `id`, etc.). See [Symbol Validity Gate](/guide/symbol-validity-gate). ## Watchdog -Mecanismo que detecta si el árbol del archivo activo no se actualizó dentro de 1 segundo después de cambiar de tab, y lanza un refresh de recuperación. Solo dispara si no hay un refresh en vuelo para esa generation. Ver [Rendimiento](/reference/rendimiento#watchdog). +Mechanism that detects if the tree for the active file has not updated within 1 second after a tab switch, and fires a recovery refresh. Only fires when no refresh is in flight for that generation. See [Performance](/reference/performance#watchdog). ## WASM -WebAssembly. Formato binario portable. GhostMap empaqueta 19 gramáticas Tree-sitter compiladas a WASM dentro de la extensión. Son código estático sin capacidad de red. +WebAssembly. Portable binary format. GhostMap packs 19 Tree-sitter grammars compiled to WASM inside the extension. They are static code with no network capability. -## Siguiente paso +## Next step -Vuelve al **[FAQ](/faq)** o a la **[Sintaxis](/reference/sintaxis)** para casos concretos. +Go back to the **[FAQ](/faq)** or to the **[Syntax](/reference/syntax)** for concrete cases. diff --git a/docs/guide/anchor.md b/docs/guide/anchor.md index c06b67d..311cb57 100644 --- a/docs/guide/anchor.md +++ b/docs/guide/anchor.md @@ -6,28 +6,28 @@ sidebar_label: Anchor # Anchor -## Definición +## Definition -Un **Anchor** es una entidad explícita creada por el usuario mediante `#nombre`. A diferencia de la metadata contextual, **tiene identidad propia** y aparece como nodo independiente en el árbol, sin necesidad de estar atado a un símbolo del lenguaje. +An **Anchor** is an explicit entity the user creates with `#name`. Unlike contextual metadata, **it has its own identity** and appears as an independent node in the tree, without being attached to a language symbol. -## Ejemplo +## Example ```ts -// @ghost #authentication description: validación jwt | status: todo +// @ghost #authentication description: jwt validation | status: todo ``` -Esto genera un nodo `authentication` en el árbol, que puede contener a su vez otros símbolos o anchors si se usa como rango. +This produces an `authentication` node in the tree, which can itself contain other symbols or anchors if used as a range. -## Los tres tipos de Anchor +## The three Anchor types -Un Anchor puede tomar tres formas, según cómo se escriba: +An Anchor takes three forms, depending on how it is written: -| Tipo | Tiene nombre (`#`) | Crea nodo propio | Página | +| Type | Has name (`#`) | Creates own node | Page | |---|---|---|---| -| **Semantic Anchor** | Sí | Sí | [Semantic Anchor](/guide/semantic-anchor) | -| **Contextual Anchor** | No | No (se pega al símbolo más cercano) | [Contextual Anchor](/guide/contextual-anchor) | -| **Range Anchor** | Sí, con `start`/`end` | Sí, y agrupa a otros nodos | [Range Anchor](/guide/range-anchor) | +| **Semantic Anchor** | Yes | Yes | [Semantic Anchor](/guide/semantic-anchor) | +| **Contextual Anchor** | No | No (attaches to the closest symbol) | [Contextual Anchor](/guide/contextual-anchor) | +| **Range Anchor** | Yes, with `start`/`end` | Yes, and groups other nodes | [Range Anchor](/guide/range-anchor) | -## Siguiente paso +## Next step -Continúa con **[Semantic Anchor](/guide/semantic-anchor)**. +Continue with **[Semantic Anchor](/guide/semantic-anchor)**. diff --git a/docs/guide/contextual-anchor.md b/docs/guide/contextual-anchor.md index 1e7d8a8..491b20b 100644 --- a/docs/guide/contextual-anchor.md +++ b/docs/guide/contextual-anchor.md @@ -6,25 +6,25 @@ sidebar_label: Contextual Anchor # Contextual Anchor -## Definición +## Definition -Un **Contextual Anchor** es una anotación `@ghost` **sin** `#nombre`. No tiene identidad propia: GhostMap busca el símbolo más cercano dentro del [radio de ownership](/guide/ownership-radius) y le adjunta la `description`/`status`. +A **Contextual Anchor** is a `@ghost` annotation **without** `#name`. It has no identity of its own: GhostMap looks for the closest symbol within the [ownership radius](/guide/ownership-radius) and attaches the `description`/`status` to it. -## Ejemplo +## Example ```ts -// @ghost description: revisar manejo de errores | status: review +// @ghost description: review error handling | status: review function processPayment() {} ``` ```text -processPayment (review) — revisar manejo de errores +processPayment (review): review error handling ``` -## Cuándo usarlo +## When to use it -Usa un Contextual Anchor cuando la nota es sobre **el símbolo que sigue inmediatamente** y no necesitas referenciarla por nombre desde otro lugar. Si quieres una nota con identidad propia (por ejemplo, para agrupar varios símbolos o para una observación general del archivo), usa un [Semantic Anchor](/guide/semantic-anchor). +Use a Contextual Anchor when the note is about **the symbol immediately below** and you do not need to reference it by name from elsewhere. If you want a note with its own identity (for example to group several symbols, or for a general file-level observation), use a [Semantic Anchor](/guide/semantic-anchor). -## Siguiente paso +## Next step -Continúa con **[Range Anchor](/guide/range-anchor)** para agrupar secciones completas de código. +Continue with **[Range Anchor](/guide/range-anchor)** to group whole code sections. diff --git a/docs/guide/ghost-description.md b/docs/guide/ghost-description.md index 8d4d351..5c5d1cf 100644 --- a/docs/guide/ghost-description.md +++ b/docs/guide/ghost-description.md @@ -6,25 +6,25 @@ sidebar_label: Ghost Description # Ghost Description -## Definición +## Definition -La **description** es el texto libre que documenta intención, contexto o trabajo pendiente, asociado a un símbolo o a un anchor. +The **description** is the free-text field that documents intent, context, or pending work tied to a symbol or to an anchor. -## Ejemplo +## Example ```ts -// @ghost description: este método no maneja refresh tokens todavía | status: todo +// @ghost description: this method does not handle refresh tokens yet | status: todo function login() {} ``` -Resultado en el árbol: +Tree result: ```text -login (todo) — este método no maneja refresh tokens todavía +login (todo): this method does not handle refresh tokens yet ``` -No hay límite de formato sobre el texto: puede ser una frase corta, una referencia a un ticket, o una nota arquitectónica más larga. +There is no format constraint on the text. It can be a short sentence, a ticket reference, or a longer architectural note. -## Siguiente paso +## Next step -Continúa con **[Anchor](/guide/anchor)** para entender la diferencia entre metadata pegada a un símbolo y un nodo con identidad propia. +Continue with **[Anchor](/guide/anchor)** to understand the difference between metadata attached to a symbol and a node with its own identity. diff --git a/docs/guide/ghost-metadata.md b/docs/guide/ghost-metadata.md index 69452a2..1c73ec0 100644 --- a/docs/guide/ghost-metadata.md +++ b/docs/guide/ghost-metadata.md @@ -6,29 +6,29 @@ sidebar_label: Ghost Metadata # Ghost Metadata -## Definición +## Definition -**Ghost Metadata** es la información asociada a un símbolo. Contiene `description`, `status` y, potencialmente, atributos futuros. +**Ghost Metadata** is information attached to a symbol. It carries `description`, `status`, and potentially future attributes. -## Punto clave +## Key point -Un comentario `@ghost` **sin nombre** (`#nombre`) **no crea un nodo propio en el árbol**. Es pura metadata que se "pega" al símbolo más cercano. +A `@ghost` comment **without a name** (`#name`) **does not create its own node in the tree**. It is pure metadata that attaches to the closest symbol. -## Ejemplo +## Example ```ts -// @ghost description: validar tokens JWT | status: todo +// @ghost description: validate jwt tokens | status: todo function login() {} ``` -Resultado en el árbol: +Tree result: ```text -login (todo) — validar tokens JWT +login (todo): validate jwt tokens ``` -**No** se genera un nodo independiente llamado `login` más un nodo Ghost separado. La metadata vive *dentro* del nodo `login`. +It does **not** produce a separate `login` node plus a separate Ghost node. The metadata lives *inside* the `login` node. -## Siguiente paso +## Next step -Continúa con **[Ghost Status](/guide/ghost-status)** para ver los valores soportados y cómo se normalizan. +Continue with **[Ghost Status](/guide/ghost-status)** to see supported values and how they are normalized. diff --git a/docs/guide/ghost-status.md b/docs/guide/ghost-status.md index 4a216a1..79d4e13 100644 --- a/docs/guide/ghost-status.md +++ b/docs/guide/ghost-status.md @@ -6,13 +6,13 @@ sidebar_label: Ghost Status # Ghost Status -## Definición +## Definition -El **status** es el estado asociado a una metadata o a un anchor. +The **status** is the state attached to a metadata block or to an anchor. -## Valores soportados +## Supported values -Estos son los valores validados por el Code Action Provider y ofrecidos por autocompletado: +These are the values validated by the Code Action Provider and offered by autocomplete: ```text todo @@ -23,19 +23,19 @@ blocked pending ``` -## Normalización +## Normalization -El valor se normaliza automáticamente: +The value is normalized automatically: -- Se convierte a minúsculas. -- Se recorta (sin espacios al inicio/fin). -- Los espacios internos se convierten en guiones: `in progress` → `in-progress`. +- Lowercased. +- Trimmed (no leading or trailing spaces). +- Internal spaces become dashes: `in progress` becomes `in-progress`. -## Quick fixes relacionados +## Related quick fixes -- Si el valor no es uno de los soportados, GhostMap sugiere el más parecido (por prefijo) o `todo` por defecto. -- Si la clave está mal escrita (por ejemplo `statu:` o `staus:`), se ofrece corregirla a `status:`. +- If the value is not one of the supported ones, GhostMap suggests the closest match (by prefix) or defaults to `todo`. +- If the key is misspelled (for example `statu:` or `staus:`), it offers a fix to `status:`. -## Siguiente paso +## Next step -Continúa con **[Ghost Description](/guide/ghost-description)**. +Continue with **[Ghost Description](/guide/ghost-description)**. diff --git a/docs/guide/ownership-radius.md b/docs/guide/ownership-radius.md index d95f774..c12e38f 100644 --- a/docs/guide/ownership-radius.md +++ b/docs/guide/ownership-radius.md @@ -6,30 +6,30 @@ sidebar_label: Ownership Radius # Ownership Radius & Ownership Resolution -## Definición +## Definition -Cuando un [Contextual Anchor](/guide/contextual-anchor) no tiene un símbolo en la misma línea, GhostMap busca hacia arriba/abajo dentro de un radio configurable de líneas (`ghostmap.ownershipRadius`, por defecto `5`) y adjunta la metadata al símbolo válido más cercano. +When a [Contextual Anchor](/guide/contextual-anchor) has no symbol on the same line, GhostMap searches up and down within a configurable line radius (`ghostmap.ownershipRadius`, default `5`) and attaches the metadata to the closest valid symbol. -## Posibles resultados (Ownership Resolution) +## Possible results (Ownership Resolution) -- **Resolved** — existe un único símbolo cercano → la metadata se adjunta. -- **Detached** — no existe ningún símbolo válido cerca → diagnóstico informativo. -- **Ambiguous** — existen múltiples candidatos igual de cercanos → diagnóstico informativo listando los candidatos. +- **Resolved**: there is exactly one nearby symbol; the metadata attaches. +- **Detached**: no valid symbol exists nearby; an informational diagnostic is shown. +- **Ambiguous**: several candidates are equally close; an informational diagnostic lists them. -## Ejemplo +## Example ```ts -// @ghost description: mejorar validación | status: todo +// @ghost description: improve validation | status: todo function login() {} ``` ```text -login (todo) — mejorar validación +login (todo): improve validation ``` -A pesar de la línea en blanco entre el comentario y la función, GhostMap resuelve la metadata al símbolo `login` porque está dentro del radio configurado. +Even with a blank line between the comment and the function, GhostMap resolves the metadata to `login` because it is inside the configured radius. -## Siguiente paso +## Next step -Continúa con **[Symbol Validity Gate](/guide/symbol-validity-gate)** para entender qué nombres pueden convertirse en nodos del árbol. +Continue with **[Symbol Validity Gate](/guide/symbol-validity-gate)** to understand which names can become nodes in the tree. diff --git a/docs/guide/philosophy.md b/docs/guide/philosophy.md index 13c3daa..0e69d43 100644 --- a/docs/guide/philosophy.md +++ b/docs/guide/philosophy.md @@ -1,46 +1,46 @@ --- id: philosophy -title: Filosofía de GhostMap -sidebar_label: Filosofía +title: GhostMap philosophy +sidebar_label: Philosophy --- -# Filosofía de GhostMap +# GhostMap philosophy ## Code-first -La planificación vive junto al código, no en una herramienta externa. Un Ghost no es un ticket que vive en otro lado y que hay que sincronizar manualmente — es una anotación que está físicamente en el archivo que describe. +Planning lives next to the code, not in an external tool. A Ghost is not a ticket that lives somewhere else and must be synced by hand. It is an annotation that sits physically in the file it describes. -## Una gramática mínima y agnóstica de lenguaje +## A minimal, language-agnostic grammar -`@ghost` es interpretable por humanos, por herramientas y por modelos de IA. No importa si tu proyecto es TypeScript, Python o Rust: la sintaxis es la misma, solo cambia el prefijo de comentario (`//` o `#`). +`@ghost` is readable by humans, by tools, and by AI models. It does not matter if your project is TypeScript, Python, or Rust. The syntax is the same. Only the comment prefix changes (`//` or `#`). -## El orden correcto: símbolos primero, Ghosts después +## The right order: symbols first, Ghosts after -Es fácil pensar en GhostMap como "un sistema de Ghosts con código adjunto". Es al revés: +It is easy to think of GhostMap as "a Ghost system with some code attached". It is the other way around: ```text -Código +Code ↓ -Símbolos (Class, Function, Method, Interface, Struct, Enum) +Symbols (Class, Function, Method, Interface, Struct, Enum) ↓ -Metadata Ghost (description, status) +Ghost metadata (description, status) ↓ -Árbol (Ghost Tree) +Tree (Ghost Tree) ``` -Primero existe un mapa de **símbolos** del proyecto —extraído del código real, con o sin anotaciones—. Después, la metadata Ghost se adjunta a esos símbolos. Esto es lo que permite que GhostMap entienda la estructura de tu proyecto incluso antes de que empieces a anotar nada. +First there is a map of **symbols** for the project (extracted from real code, with or without annotations). Then the Ghost metadata attaches to those symbols. That is what lets GhostMap understand the structure of your project before you annotate anything. -## Principios de diseño +## Design principles -1. **Code first** — el código es la fuente de verdad. -2. **Minimal syntax** — una gramática simple, sin ceremonia. -3. **Language agnostic** — funciona igual en más de 15 lenguajes. -4. **Fast navigation** — un clic te lleva exactamente al lugar correcto. -5. **Structural understanding** — el árbol refleja la jerarquía real del código. -6. **AI-ready architecture** — la gramática está pensada para ser leída por modelos de IA tan fácilmente como por humanos. -7. **Workspace awareness** — GhostMap entiende el proyecto, no solo el archivo abierto. -8. **Incremental scalability** — funciona igual de bien en un archivo de 50 líneas que en uno de 50,000 (ver [Loading Policy](/architecture/loading-policy)). +1. **Code first**: code is the source of truth. +2. **Minimal syntax**: a simple grammar, no ceremony. +3. **Language agnostic**: works the same across 19 languages. +4. **Fast navigation**: one click takes you to the exact place. +5. **Structural understanding**: the tree reflects the real hierarchy of the code. +6. **AI-ready architecture**: the grammar is meant to be read by AI models as easily as by humans. +7. **Workspace awareness**: GhostMap understands the project, not just the open file. +8. **Incremental scalability**: it works the same in a 50-line file as in a 50,000-line file (see [Loading Policy](/architecture/loading-policy)). -## Siguiente paso +## Next step -Continúa con **[Symbol](/guide/symbol)** para entender la primera capa del modelo: cómo GhostMap extrae los símbolos de tu código. +Continue with **[Symbol](/guide/symbol)** to understand the first layer of the model: how GhostMap extracts symbols from your code. diff --git a/docs/guide/range-anchor.md b/docs/guide/range-anchor.md index 23889c3..1c6db29 100644 --- a/docs/guide/range-anchor.md +++ b/docs/guide/range-anchor.md @@ -6,50 +6,52 @@ sidebar_label: Range Anchor # Range Anchor -## Definición +## Definition -Un **Range Anchor** permite delimitar una región completa de código bajo un mismo Anchor. +A **Range Anchor** groups a whole section of code under a single named node, with `#name start` opening the range and `@ghost end` closing it. + +## Example ```ts -// @ghost #refactor-pagos start description: dividir este servicio en 3 | status: todo +// @ghost #payments-refactor start description: split this service into 3 microservices | status: in-progress class PaymentService { charge() {} refund() {} + + // @ghost description: pending move to billing-service | status: todo reconcile() {} + + generateInvoice() {} } // @ghost end ``` ```text -refactor-pagos (todo) — dividir este servicio en 3 +payments-refactor (in-progress): split this service into 3 microservices └── PaymentService ├── charge ├── refund - └── reconcile + ├── reconcile (todo): pending move to billing-service + └── generateInvoice ``` -## Reglas de jerarquía (containment) - -- Un símbolo que **empieza** dentro del rango de un Range Anchor pertenece a ese anchor, incluso si su cuerpo se extiende más allá de la línea `@ghost end`. -- La jerarquía se construye por **contención de rangos**, no por nombres compuestos: nunca verás algo como `AuthService.login()` como identificador — la relación padre-hijo se expresa directamente en el árbol. - -## Importante: el nombre es obligatorio para que se vea +## Important: the name is required for the range to show -Un `@ghost ... start` **sin** `#nombre` es válido sintácticamente, pero al no tener nombre **no se renderiza como nodo en el árbol**. Si quieres un rango visible en el Ghost Tree, siempre necesitas `#nombre`: +A `@ghost ... start` **without** `#name` is syntactically valid, but with no name it **does not render as a node in the tree**. If you want a visible range in the Ghost Tree, you always need `#name`: ```ts -// ✅ Crea un nodo visible "refactor-pagos" -// @ghost #refactor-pagos start description: ... | status: ... +// Creates a visible node "payments-refactor" +// @ghost #payments-refactor start description: ... | status: ... -// ❌ Válido, pero no aparece como nodo en el árbol +// Valid, but does not appear as a node in the tree // @ghost start description: ... | status: ... ``` -## Ejemplo antes / después +## Before / after example -**Antes** — un archivo grande, sin estructura, donde un dev nuevo no sabe por dónde empezar ni qué partes están "en obras": +**Before**: a large file with no structure, where a new dev does not know where to start or which parts are "under construction": ```ts class PaymentService { @@ -68,16 +70,16 @@ PaymentService └── generateInvoice ``` -**Después** — con un Range Anchor agrupando el trabajo en curso: +**After**: with a Range Anchor grouping the in-flight work: ```ts -// @ghost #refactor-pagos start description: dividir este servicio en 3 microservicios | status: in-progress +// @ghost #payments-refactor start description: split this service into 3 microservices | status: in-progress class PaymentService { charge() {} refund() {} - // @ghost description: pendiente mover a billing-service | status: todo + // @ghost description: pending move to billing-service | status: todo reconcile() {} generateInvoice() {} @@ -87,18 +89,18 @@ class PaymentService { ``` ```text -refactor-pagos (in-progress) — dividir este servicio en 3 microservicios +payments-refactor (in-progress): split this service into 3 microservices └── PaymentService ├── charge ├── refund - ├── reconcile (todo) — pendiente mover a billing-service + ├── reconcile (todo): pending move to billing-service └── generateInvoice ``` -Con un solo vistazo, cualquier dev entiende: este archivo completo está en medio de un refactor, y específicamente `reconcile` es lo siguiente que hay que mover. +At a glance, anyone can tell: this whole file is in the middle of a refactor, and `reconcile` is specifically the next thing to move. -**Caso de uso típico:** refactors grandes, migraciones de módulos, o "zonas calientes" del código que requieren contexto adicional antes de tocarlas. +**Typical use cases:** large refactors, module migrations, or "hot zones" of the code that need extra context before being touched. -## Siguiente paso +## Next step -Continúa con **[Ownership Radius](/guide/ownership-radius)** para entender cómo GhostMap decide a qué símbolo se pega un Contextual Anchor. +Continue with **[Ownership Radius](/guide/ownership-radius)** to understand how GhostMap decides which symbol a Contextual Anchor attaches to. diff --git a/docs/guide/semantic-anchor.md b/docs/guide/semantic-anchor.md index f63254d..62a58a3 100644 --- a/docs/guide/semantic-anchor.md +++ b/docs/guide/semantic-anchor.md @@ -6,27 +6,27 @@ sidebar_label: Semantic Anchor # Semantic Anchor -## Definición +## Definition -Un **Semantic Anchor** es un Anchor con nombre explícito (`#nombre`). +A **Semantic Anchor** is an Anchor with an explicit name (`#name`). -## Características +## Properties -- Tiene nombre propio (`#auth`, `#refactor-pagos`, etc.). -- Aparece en el árbol como nodo propio. -- Puede contener otros elementos (si se usa como [Range Anchor](/guide/range-anchor)). -- Puede existir de forma totalmente independiente, sin estar pegado a ningún símbolo de código — por ejemplo, para una nota arquitectónica general. +- It has its own name (`#auth`, `#refactor-payments`, etc.). +- It appears in the tree as its own node. +- It can contain other items (when used as a [Range Anchor](/guide/range-anchor)). +- It can exist fully independent of any code symbol, for example as a general architectural note. -## Ejemplo +## Example ```ts -// @ghost #auth description: validar JWT | status: todo +// @ghost #auth description: validate jwt | status: todo ``` ```text -auth (todo) — validar JWT +auth (todo): validate jwt ``` -## Siguiente paso +## Next step -Continúa con **[Contextual Anchor](/guide/contextual-anchor)**. +Continue with **[Contextual Anchor](/guide/contextual-anchor)**. diff --git a/docs/guide/symbol-validity-gate.md b/docs/guide/symbol-validity-gate.md index 246710a..f6f8d44 100644 --- a/docs/guide/symbol-validity-gate.md +++ b/docs/guide/symbol-validity-gate.md @@ -6,48 +6,47 @@ sidebar_label: Symbol Validity Gate # Symbol Validity Gate -## Definición +## Definition -El **Symbol Validity Gate** es un filtro centralizado que decide si un nombre extraído del código puede convertirse en un nodo del árbol. Se aplica en **todas** las rutas de extracción (LSP, tree-sitter, regex fallback, PHP). +The **Symbol Validity Gate** is a centralized filter that decides whether a name extracted from code can become a node in the tree. It applies on **every** extraction path (LSP, Tree-sitter, regex fallback, PHP). -## Un nombre se rechaza si +## A name is rejected if -- Tiene menos de 2 caracteres, o es `` / empieza con `<`. -- Es un identificador de 1–2 letras en minúscula (`e`, `cb`, `fn`...). -- Está en la lista de "nombres ruido" (`NOISE_NAMES`): `callback`, `cb`, `fn`, `func`, `handler`, `resolve`, `reject`, `next`, `done`, `err`, `error`, `e`, `evt`, `event`, `res`, `req`, `ctx`, `data`, `item`, `then`, `catch`, `finally`, `body`, `args`, `kwargs`, `params`, `opts`, `options`. -- Es una palabra reservada del lenguaje (lista cross-language: `if`, `class`, `function`, `return`, `async`, `self`, `this`, etc. — más de 100 palabras cubriendo JS/TS, Python, Rust, Go, Java, C#, C/C++, Ruby, SQL, entre otros). +- It has fewer than 2 characters, or it is `` / starts with `<`. +- It is a 1 to 2 letter lowercase identifier (`e`, `cb`, `fn`, etc.). +- It is in the "noise names" list (`NOISE_NAMES`): `callback`, `cb`, `fn`, `func`, `handler`, `resolve`, `reject`, `next`, `done`, `err`, `error`, `e`, `evt`, `event`, `res`, `req`, `ctx`, `data`, `item`, `then`, `catch`, `finally`, `body`, `args`, `kwargs`, `params`, `opts`, `options`. +- It is a reserved word of the language (a cross-language list of more than 100 words covering JS/TS, Python, Rust, Go, Java, C#, C/C++, Ruby, SQL, and others). -## Por qué importa +## Why it matters -Esto explica por qué un callback anónimo (`.then(res => ...)`) o una función `function e() {}` **no** aparecen como nodos en el Ghost Tree. Es intencional, para evitar ruido. +This explains why an anonymous callback (`.then(res => ...)`) or a function `function e() {}` **does not** appear as a node in the Ghost Tree. It is intentional, to avoid noise. -## Ejemplos de código que intencionalmente NO genera nodos +## Examples of code that intentionally does NOT create nodes ```ts -// ❌ No aparece: nombre de 1-2 caracteres en minúscula +// Does not appear: 1 to 2 character lowercase name function e() {} -// ❌ No aparece: callback anónimo en .then() +// Does not appear: anonymous callback in .then() fetchData().then(res => { console.log(res); }); -// ❌ No aparece: "data" está en NOISE_NAMES +// Does not appear: "data" is in NOISE_NAMES const data = items.map(item => transform(item)); -// ❌ No aparece: "constructor" es palabra reservada / context-sensitive +// Does not appear: "constructor" is reserved / context-sensitive class Foo { constructor() {} } -// ✅ Sí aparece: nombre descriptivo, no reservado, no ruido +// Does appear: descriptive name, not reserved, not noise function calculateMonthlyInterest(principal: number) {} ``` -:::tip -Si una función o variable que esperabas ver no aparece en el árbol, probablemente cae en uno de estos casos — no es un error de GhostMap. -::: +> **Note:** +> If a function or variable you expected to see is missing from the tree, it probably falls in one of these cases. It is not a GhostMap bug. -## Siguiente paso +## Next step -Has completado la sección de Conceptos. Continúa con la **[Referencia de sintaxis](/reference/sintaxis)** para ver todas las formas válidas de escribir `@ghost`. +You have finished the Guide section. Continue with the **[Syntax reference](/reference/syntax)** to see every valid form of `@ghost`. diff --git a/docs/guide/symbol.md b/docs/guide/symbol.md index 5f2db54..d86ff0c 100644 --- a/docs/guide/symbol.md +++ b/docs/guide/symbol.md @@ -6,43 +6,43 @@ sidebar_label: Symbol # Symbol -## Definición +## Definition -Un **Symbol** es la unidad semántica extraída del código fuente. Es la base de todo el sistema: GhostMap construye primero el mapa de símbolos del proyecto y luego le aplica la metadata Ghost. +A **Symbol** is the semantic unit extracted from source code. It is the base of the whole system: GhostMap first builds the project's symbol map and then layers Ghost metadata on top. -## Tipos de símbolo soportados +## Supported symbol types -GhostMap reconoce: **Class, Function, Method, Interface, Struct, Enum**. +GhostMap recognizes **Class, Function, Method, Interface, Struct, and Enum**. -Internamente se agrupan en dos categorías: +Internally they group into two categories: -- `'function'` — incluye Function, Method y Constructor. -- `'class'` — incluye Class, Interface, Struct y Enum. +- `'function'`: includes Function, Method, and Constructor. +- `'class'`: includes Class, Interface, Struct, and Enum. -## Cómo se extraen +## How they are extracted -GhostMap intenta, en este orden: +GhostMap tries, in this order: -1. **LSP** (`vscode.executeDocumentSymbolProvider`) — si el lenguaje tiene un *language server* activo, es la fuente preferida. -2. **Tree-sitter** — gramáticas WASM por lenguaje. -3. **Regex fallback** — patrones por lenguaje cuando no hay LSP ni grammar de tree-sitter disponible (o falla el parseo). -4. **PHP/Blade** — tiene su propio parser regex dedicado. +1. **LSP** (`vscode.executeDocumentSymbolProvider`): if the language has an active language server, it is the preferred source. +2. **Tree-sitter**: per-language WASM grammars. +3. **Regex fallback**: per-language patterns when no LSP or Tree-sitter grammar is available (or when parsing fails). +4. **PHP/Blade**: has its own dedicated regex parser. -## Lenguajes soportados +## Supported languages JavaScript, TypeScript, TSX, Python, PHP, Java, C#, Go, Rust, C, C++, Ruby, Dart, Elixir, Groovy, Julia, Objective-C, Scala, Solidity. -## Ejemplo +## Example ```ts -// archivo: auth.service.ts +// file: auth.service.ts export class AuthService { login() { /* ... */ } logout() { /* ... */ } } ``` -Resultado (simplificado): +Result (simplified): ```text AuthService (class) @@ -50,8 +50,8 @@ AuthService (class) └── logout (function) ``` -Nota que este árbol existe **sin ninguna anotación `@ghost`** — es el mapa de símbolos puro. La metadata Ghost se le adjunta encima (ver [Ghost Metadata](/guide/ghost-metadata)). +This tree exists **without any `@ghost` annotation**. It is the pure symbol map. Ghost metadata attaches on top of it (see [Ghost Metadata](/guide/ghost-metadata)). -## Siguiente paso +## Next step -Continúa con **[Ghost Metadata](/guide/ghost-metadata)** para ver cómo se adjunta información a estos símbolos. +Continue with **[Ghost Metadata](/guide/ghost-metadata)** to see how information attaches to these symbols. diff --git a/docs/install.md b/docs/install.md new file mode 100644 index 0000000..0a5efce --- /dev/null +++ b/docs/install.md @@ -0,0 +1,64 @@ +--- +id: install +title: Install +sidebar_label: Install +slug: /install +--- + +# Install + +## What is a VSIX? + +A `.vsix` file is the packaged VS Code extension format, the same thing the Marketplace serves under the hood. As a normal user you do not build it: the GhostMap maintainers build the `.vsix` from the private extension source and send you that file. Installing it is one command or one menu click. + +## Current install reality + +GhostMap is not yet published on the VS Code Marketplace or Open VSX. The current way to install it is a **locally built VSIX**, distributed on request. + +### Request a VSIX + +Send an email to [getghostmap@proton.me](mailto:getghostmap@proton.me?subject=GhostMap%20VSIX%20request) describing your use case. You will receive the same `.vsix` binary the extension repository produces. + +### Install it + +Once you have the `.vsix` file: + +```powershell +code --install-extension ghostmap-0.5.0.vsix +``` + +Or, in VS Code: open the **Extensions** panel, click the `...` menu, choose **Install from VSIX...**, and pick the file. + +After install: + +1. Open a file in any supported language (TypeScript, Python, Rust, C#, Java, PHP, C++, Go, Ruby, Dart, and others: 19 in total). +2. Open the **GhostMap** view in the activity bar. +3. The tree shows every detected symbol; click an item to jump. +4. Drop a `@ghost` anchor in a comment: it appears in the tree. + +### Update or uninstall + +To update, install a newer `.vsix` over the existing one with the same command. To uninstall, run: + +```powershell +code --uninstall-extension ghostmap.ghostmap +``` + +Or use the Extensions panel: find GhostMap, click the gear icon, choose **Uninstall**. + +## Planned channels (not active today) + +| Channel | Status | Notes | +| --- | --- | --- | +| Local VSIX on request | Active | Email `getghostmap@proton.me`. | +| GitHub Releases | Planned, post-tag | No public tagged release exists yet. | +| VS Code Marketplace | Planned | Depends on publisher onboarding. No placeholder link is published anywhere. | +| Open VSX | Planned | Bridge for VSCodium and Open VSX-compatible editors; needs a namespace and token. | + +When a channel becomes active, the link will appear here and on the docs landing page. The project does not publish placeholder Marketplace, Open VSX, Lemon Squeezy, Patreon, or Ko-fi links that do not resolve. + +## Next step + +- Check [Requirements](/get-started/requirements) if you want to confirm GhostMap fits your machine and language. +- Continue with [First 5 minutes](/get-started/first-5-minutes) to write your first `@ghost`. +- See [Install from VSIX](/vsix-install) for offline, pinning, and corporate setups. diff --git a/docs/intro.md b/docs/intro.md index d0f3d64..17a9a87 100644 --- a/docs/intro.md +++ b/docs/intro.md @@ -2,55 +2,63 @@ id: intro title: GhostMap slug: / -sidebar_label: Introducción +sidebar_label: Start --- -# Estructura de proyecto, dentro de tu código +# Project structure, inside your code -GhostMap es una extensión de VS Code que convierte comentarios estructurados (`@ghost`) en un mapa navegable de tu proyecto: un árbol semántico que vive junto al código, no en una herramienta externa. +GhostMap is a VS Code extension that turns structured `@ghost` comments into a navigable map of your code. -## El problema +## The idea -Los `TODO`, `FIXME` y `HACK` que ya usas no tienen estructura. No se pueden filtrar, no tienen un estado claro y, con el tiempo, se pierden entre miles de líneas. GhostMap les da una gramática mínima y los conecta directamente con los símbolos reales del código: clases, funciones, métodos, interfaces. +`TODO`, `FIXME`, and `HACK` comments are useful, but they have no structure. GhostMap gives them a small grammar and connects them to real symbols: classes, functions, methods, interfaces, and anchors. -> *"El código es la fuente principal de verdad. Las tareas, refactorizaciones, documentación pendiente y observaciones arquitectónicas deben existir cerca de la implementación que describen."* +> The code stays the source of truth. Notes about the code live next to the code. -## Cómo se ve en la práctica +## How it looks -Este comentario: +Write this: ```ts class AuthService { - - // @ghost description: revisar seguridad | status: todo + // @ghost description: validate jwt tokens | status: review login() { // ... } + + // @ghost description: revoke session | status: done + logout() { + // ... + } } ``` -se convierte automáticamente en esto, en el panel lateral de GhostMap: +GhostMap shows this in the side panel: ```text AuthService -└── login (todo) — revisar seguridad +├── login (review): validate jwt tokens +└── logout (done): revoke session ``` -Sin configuración adicional, sin archivos externos. El árbol se reconstruye solo cada vez que editas. +No extra files. No external tracker. The tree rebuilds as you edit. -## Por dónde empezar +## Start here -- **[Instalación](/get-started/instalacion)** — genera un VSIX local e instálalo en VS Code Desktop. -- **[Primeros 5 minutos](/get-started/primeros-5-minutos)** — escribe tu primer `@ghost` y mira aparecer el árbol. -- **[Guía / Conceptos](/guide/philosophy)** — entiende los fundamentos: símbolos, anchors, ownership. -- **[Referencia](/reference/sintaxis)** — sintaxis completa de `@ghost`, comandos y settings. +- **[Overview](/overview)**: what GhostMap is and how it fits in your editor. +- **[Install](/install)**: current install path and planned channels. +- **[First 5 minutes](/get-started/first-5-minutes)**: write your first `@ghost` and see the tree. +- **[Syntax reference](/reference/syntax)**: every valid `@ghost` form. +- **[Settings](/reference/settings)**: tune ownership radius, file budgets, and more. +- **[Legal & Support](/legal-support)**: license summary and contact. +- **[Changelog](/changelog)**: release history. -## Tres tipos de Ghost +## Three Ghost types -| Tipo | Ejemplo | Qué hace | +| Type | Example | What it does | |---|---|---| -| **Contextual** | `// @ghost description: ... \| status: ...` | Se adjunta automáticamente al símbolo más cercano. | -| **Named (Semantic Anchor)** | `// @ghost #nombre description: ...` | Crea un nodo propio en el árbol, con identidad propia. | -| **Range** | `// @ghost #nombre start ... // @ghost end` | Agrupa una sección completa de código bajo un mismo nodo. | +| **Contextual** | `// @ghost description: ... \| status: ...` | Attaches to the nearest symbol. | +| **Named (Semantic Anchor)** | `// @ghost #name description: ...` | Creates its own node in the tree. | +| **Range** | `// @ghost #name start ... // @ghost end` | Groups a whole code section under one node. | -GhostMap Core —todo lo cubierto en esta documentación— es el alcance documentado para V1. GhostMap es un producto propiedad del *GhostMap project owner* (MarxWellB), distribuido bajo la **GhostMap Free Non-Commercial License**: uso personal, educativo y de evaluación sin costo; cualquier uso comercial, de empresa, en producción o que genere ingresos requiere autorización escrita. Las consultas de licenciamiento comercial van a [getghostmap@proton.me](mailto:getghostmap@proton.me). +GhostMap is source-available under the **GhostMap Free Non-Commercial License**. Personal, educational, and evaluation use is free. Commercial use needs written authorization. For licensing questions, write to [getghostmap@proton.me](mailto:getghostmap@proton.me). diff --git a/docs/keyboard-shortcuts.md b/docs/keyboard-shortcuts.md index 96e12e0..668b581 100644 --- a/docs/keyboard-shortcuts.md +++ b/docs/keyboard-shortcuts.md @@ -1,42 +1,42 @@ --- id: keyboard-shortcuts -title: Atajos de teclado -sidebar_label: Atajos de teclado +title: Keyboard shortcuts +sidebar_label: Keyboard shortcuts --- -# Atajos de teclado +# Keyboard shortcuts -## Atajos por defecto +## Default shortcuts -| Acción | Windows / Linux | macOS | Disponible cuando | +| Action | Windows / Linux | macOS | Available when | |---|---|---|---| -| `GhostMap: Refresh` | `Ctrl+Alt+G` | `Cmd+Alt+G` | El editor tiene foco | +| `GhostMap: Refresh` | `Ctrl+Alt+G` | `Cmd+Alt+G` | The editor has focus | -El resto de los comandos (`Filter`, `Search`, `Reset`) no tienen atajo por defecto. Están disponibles desde: +The other commands (`Filter`, `Search`, `Reset`) have no default shortcut. They are available from: -- **La paleta de comandos** (`Ctrl+Shift+P` / `Cmd+Shift+P`), buscando `GhostMap: ...`. -- **La toolbar del panel GhostMap**, en la barra lateral izquierda. +- **The command palette** (`Ctrl+Shift+P` / `Cmd+Shift+P`), searching `GhostMap: ...`. +- **The GhostMap panel toolbar**, in the left side bar. -## Asignar tus propios atajos +## Assigning your own shortcuts -VS Code te permite asignar cualquier atajo a cualquier comando: +VS Code lets you assign any shortcut to any command: -1. Abre `File → Preferences → Keyboard Shortcuts` (`Ctrl+K Ctrl+S` / `Cmd+K Cmd+S`). -2. Busca `GhostMap`. -3. Click en el lápiz junto al comando, presiona la combinación que quieras, Enter. +1. Open `File → Preferences → Keyboard Shortcuts` (`Ctrl+K Ctrl+S` / `Cmd+K Cmd+S`). +2. Search `GhostMap`. +3. Click the pencil next to the command, press the combination you want, Enter. -Comandos disponibles para asignar: +Commands available to bind: -| Comando | ID | +| Command | ID | |---|---| -| Refrescar el árbol del archivo activo | `ghostmap.refresh` | -| Filtrar el árbol por status | `ghostmap.filterByStatus` | -| Buscar en el árbol | `ghostmap.search` | -| Limpiar filtros y búsqueda | `ghostmap.reset` | +| Refresh the active file's tree | `ghostmap.refresh` | +| Filter the tree by status | `ghostmap.filterByStatus` | +| Search in the tree | `ghostmap.search` | +| Clear filters and search | `ghostmap.reset` | -## Atajos sugeridos +## Suggested shortcuts -Si usas GhostMap a diario, estas asignaciones suelen funcionar bien: +If you use GhostMap daily, these usually work well: ```json [ @@ -46,23 +46,23 @@ Si usas GhostMap a diario, estas asignaciones suelen funcionar bien: ] ``` -Pégalas en tu `keybindings.json` (accesible desde la paleta: `Preferences: Open Keyboard Shortcuts (JSON)`). +Paste them into your `keybindings.json` (accessible from the palette: `Preferences: Open Keyboard Shortcuts (JSON)`). -## Snippets relacionados +## Related snippets -No son atajos de comando, sino prefijos que activas con **Tab** dentro de un archivo: +These are not command shortcuts but prefixes you trigger with **Tab** inside a file: -| Prefijo | Resultado | +| Prefix | Result | |---|---| -| `gh` | Point Anchor con nombre (línea `//`) | -| `gw` | Contextual Anchor (línea `//`) | -| `gr` | Range Anchor (línea `//`) | -| `gl` | Point Anchor (línea `#`) | -| `gxl` | Contextual Anchor (línea `#`) | -| `gxr` | Range Anchor (línea `#`) | +| `gh` | Named Point Anchor (line `//`) | +| `gw` | Contextual Anchor (line `//`) | +| `gr` | Range Anchor (line `//`) | +| `gl` | Named Point Anchor (line `#`) | +| `gxl` | Contextual Anchor (line `#`) | +| `gxr` | Range Anchor (line `#`) | -Ver [Sintaxis](/reference/sintaxis) para los detalles. +See [Syntax](/reference/syntax) for details. -## Siguiente paso +## Next step -Continúa con **[Settings](/reference/settings)** para personalizar los defaults. +Continue with **[Settings](/reference/settings)** to customize the defaults. diff --git a/docs/legal-support.md b/docs/legal-support.md new file mode 100644 index 0000000..d2cf463 --- /dev/null +++ b/docs/legal-support.md @@ -0,0 +1,49 @@ +--- +id: legal-support +title: Legal & Support +sidebar_label: Legal & Support +slug: /legal-support +--- + +# Legal & Support + +> The `LICENSE`, `THIRD_PARTY_NOTICES.txt`, Privacy Policy, Terms of Use, and Disclaimer files shipped with the extension and rendered in the docs site govern actual use. + +## License (summary) + +GhostMap is owned by the GhostMap project owner / MarxWellB and is source-available under the **GhostMap Free Non-Commercial License**. + +- **Free for:** personal, educational, evaluation and testing, and other non-commercial use. +- **Requires written authorization for:** company, business, production, revenue-generating, client, resale, white-label, marketplace-republish, and competing-product use. +- **Commercial licensing & legal contact:** [getghostmap@proton.me](mailto:getghostmap@proton.me). + +Voluntary donations and supporter contributions are separate from commercial authorization and do not grant commercial, company, or production rights. Supporter benefits are not pricing tiers and do not transfer license rights. + +## Legal documents + +| Document | Where to read it | +| --- | --- | +| Full license text | The `LICENSE` file shipped inside the VSIX. The pages below summarize and link the [Terms of Use](/legal/terms), [Privacy Policy](/legal/privacy), and [Third-Party Notices](/legal/notices). | +| Privacy Policy | [/legal/privacy](/legal/privacy) | +| Terms of Use | [/legal/terms](/legal/terms) | +| Third-Party Notices | [/legal/notices](/legal/notices) | +| Disclaimer | [/legal/disclaimer](/legal/disclaimer) | + +## Third-party components + +GhostMap bundles `web-tree-sitter` and 19 Tree-sitter grammars. Each component keeps its own upstream license. The exact upstream `LICENSE` and `SOURCE.txt` files for every bundled grammar ship inside the extension, under `wasm/licenses/`, and are mirrored in the `THIRD_PARTY_NOTICES.txt` file in the VSIX. + +## Support + +There is one support channel today: [getghostmap@proton.me](mailto:getghostmap@proton.me). + +Use this address for: + +- Requesting a VSIX (see [Install](/install)). +- Bug reports and troubleshooting. +- Commercial licensing inquiries. +- Partnership and integration questions. + +### Voluntary support platforms + +Voluntary supporter platforms (for example Lemon Squeezy, Patreon, Ko-fi) are **not active today**. They may be adopted later as voluntary processors. When a platform becomes active, the link will appear here and on the docs site. The project does not publish placeholder URLs that do not resolve. diff --git a/docs/legal/disclaimer.md b/docs/legal/disclaimer.md index 0e4142a..5300c62 100644 --- a/docs/legal/disclaimer.md +++ b/docs/legal/disclaimer.md @@ -6,13 +6,10 @@ sidebar_label: Disclaimer # Disclaimer -> **Nota:** Esta página está en inglés porque define límites técnicos y legales que tienen que ser inequívocos. La versión definitiva de los documentos legales es la inglesa. Si necesitas la información en español, los puntos clave están resumidos en [Estado del proyecto](/status/estado-del-proyecto). - **Effective date:** June 18, 2026 · **Version:** 1.0 -:::caution -GhostMap is currently in pre-release. Some features described in this documentation are best-effort. Read this page before relying on GhostMap output for critical work. -::: +> **Important:** +> GhostMap is currently in pre-release. Some features described in this documentation are best-effort. Read this page before relying on GhostMap output for critical work. ## Pre-release software @@ -46,14 +43,14 @@ These are tracked for resolution in upcoming rounds. Roughly 20 additional languages (Kotlin, Swift, Haskell, OCaml, Clojure, Lua, R, Bash, the SQL family, …) are on the roadmap but **not supported today**. The expansion is gated on a set of validation and packaging risks surfaced by prior audits of the existing 19-grammar bundle: -- **Dart WASM load failure risk** — the Dart grammar has been observed to fail to load on some Electron/Node combinations and silently fall back to regex. -- **Invalid Elixir / Objective-C queries** — existing query files reference nodes the upstream grammars do not always expose; new queries we ship must be validated against the grammar version we bundle. -- **Weak Julia coverage** — many definition shapes (macros, `@inline`-emitted defs) are not extracted; new similar-shape languages need a fixture set proving the shapes we claim to cover. -- **Duplicate symbol issues** — some grammar packs expose colliding WASM symbol names that mis-load at runtime without a duplicate-symbol guard. -- **Non-reproducible WASM provenance** — today's WASMs are checked-in artifacts; the expansion needs a reproducible build job before adding more. -- **Fallback masking broken grammars** — the LSP → Tree-sitter → regex chain hides grammar regressions; the expansion needs a per-grammar load + sample-query smoke that fails loudly. +- **Dart WASM load failure risk**: the Dart grammar has been observed to fail to load on some Electron/Node combinations and silently fall back to regex. +- **Invalid Elixir / Objective-C queries**: existing query files reference nodes the upstream grammars do not always expose; new queries we ship must be validated against the grammar version we bundle. +- **Weak Julia coverage**: many definition shapes (macros, `@inline`-emitted defs) are not extracted; new similar-shape languages need a fixture set proving the shapes we claim to cover. +- **Duplicate symbol issues**: some grammar packs expose colliding WASM symbol names that mis-load at runtime without a duplicate-symbol guard. +- **Non-reproducible WASM provenance**: today's WASMs are checked-in artifacts; the expansion needs a reproducible build job before adding more. +- **Fallback masking broken grammars**: the LSP → Tree-sitter → regex chain hides grammar regressions; the expansion needs a per-grammar load + sample-query smoke that fails loudly. -Until a candidate language passes all of those gates (and gets a fixture row in the matrix tests), it does not appear in [Requisitos](/get-started/requisitos) or the language sections of the marketing site. +Until a candidate language passes all of those gates (and gets a fixture row in the matrix tests), it does not appear in [Requirements](/get-started/requirements) or the language sections of the marketing site. ## "Navigational aid" framing diff --git a/docs/legal/notices.md b/docs/legal/notices.md index 1f0a111..280e2b6 100644 --- a/docs/legal/notices.md +++ b/docs/legal/notices.md @@ -44,7 +44,7 @@ The following 19 grammars ship as precompiled WebAssembly files inside the exten ### Provenance note -The exact git commit/tag used to compile each shipped WASM artifact is not recorded in this repository — the WASMs are checked-in artifacts rather than reproducibly built. Each per-component `SOURCE.txt` records the upstream default-branch HEAD commit at the time the LICENSE text was fetched. The shipped LICENSE files are the best available license notices for the bundled artifacts under that provenance disclosure; if the upstream license for a grammar later changes, the notice that shipped with a given release continues to govern that release. This provenance gap is acknowledged here, not hidden, and will be closed when the WASM build job becomes reproducible (see the language-pack expansion gate in [Disclaimer](/legal/disclaimer)). +The exact git commit/tag used to compile each shipped WASM artifact is not recorded in this repository: the WASMs are checked-in artifacts rather than reproducibly built. Each per-component `SOURCE.txt` records the upstream default-branch HEAD commit at the time the LICENSE text was fetched. The shipped LICENSE files are the best available license notices for the bundled artifacts under that provenance disclosure; if the upstream license for a grammar later changes, the notice that shipped with a given release continues to govern that release. This provenance gap is acknowledged here, not hidden, and will be closed when the WASM build job becomes reproducible (see the language-pack expansion gate in [Disclaimer](/legal/disclaimer)). ## VS Code Extension API diff --git a/docs/legal/privacy.md b/docs/legal/privacy.md index 35d6c74..4a45ae1 100644 --- a/docs/legal/privacy.md +++ b/docs/legal/privacy.md @@ -6,13 +6,10 @@ sidebar_label: Privacy Policy # Privacy Policy -> **Nota:** Esta página está en inglés porque la política tiene efecto contractual y debe ser inequívoca. La versión definitiva es la inglesa. - **Effective date:** June 20, 2026 · **Version:** 1.1 -:::tip The whole policy in one line -The GhostMap extension runs on your machine, makes no network calls of its own, transmits no source code or metadata off your machine, ships no telemetry or analytics, and does not communicate with the maintainers. Site and support-platform caveats are covered below. -::: +> **The whole policy in one line:** +> The GhostMap extension runs on your machine, makes no network calls of its own, transmits no source code or metadata off your machine, ships no telemetry or analytics, and does not communicate with the maintainers. Site and support-platform caveats are covered below. ## 1. What data we collect @@ -63,7 +60,7 @@ This statement describes the current technical design and maintainer data postur ## 9. Future enterprise-oriented roadmap and server services -The enterprise-oriented integrations described in [Roadmap — Visión v2](/roadmap/vision-v2) (Jira / Slack flow, Ghost Threads, Ghost Graph, dashboards, AI explanations, permissions and audit log) are **not implemented today** and no part of GhostMap currently communicates with any of those services. Nothing in this policy should be read as a commitment that those integrations will exist, or that they will preserve the current local-only posture. +The enterprise-oriented integrations described in [Roadmap: v2 vision](/roadmap/v2) (Jira / Slack flow, Ghost Threads, Ghost Graph, dashboards, AI explanations, permissions and audit log) are **not implemented today** and no part of GhostMap currently communicates with any of those services. Nothing in this policy should be read as a commitment that those integrations will exist, or that they will preserve the current local-only posture. If a future version of GhostMap ever introduces an optional feature that involves data collection or transmission (for example, an optional opt-in telemetry signal, or an Enterprise capability with server services), that feature will be: diff --git a/docs/legal/terms.md b/docs/legal/terms.md index e01f1fc..ab61f36 100644 --- a/docs/legal/terms.md +++ b/docs/legal/terms.md @@ -6,13 +6,10 @@ sidebar_label: Terms of Use # Terms of Use -> **Nota:** Esta página está en inglés porque los términos tienen efecto contractual y deben ser inequívocos. La versión definitiva es la inglesa. - **Effective date:** June 20, 2026 · **Version:** 1.2 -:::caution Short version -Personal, educational, evaluation/testing, and other non-commercial use are allowed. Company, production, revenue-generating, resale, white-label, marketplace, and competing commercial-product use require written authorization. -::: +> **Short version:** +> Personal, educational, evaluation/testing, and other non-commercial use are allowed. Company, production, revenue-generating, resale, white-label, marketplace, and competing commercial-product use require written authorization. ## 1. Product identification & ownership @@ -63,7 +60,7 @@ GhostMap incorporates third-party components, each licensed under its own terms. ## 9. Future roadmap and server services -Future team-oriented capabilities and the integrations described in [Roadmap — Visión v2](/roadmap/vision-v2) (Jira / Slack flow, Ghost Threads, Ghost Graph, dashboards, AI explanations, permissions and audit log) are **not implemented today**. Future commercial or server-service components, if released, will carry their own license terms and privacy notices, and will require an explicit opt-in before any data leaves a user's machine. Nothing in these Terms should be read as a commitment that such components will exist or that they will preserve the local-only posture of V1. +Future team-oriented capabilities and the integrations described in [Roadmap: v2 vision](/roadmap/v2) (Jira / Slack flow, Ghost Threads, Ghost Graph, dashboards, AI explanations, permissions and audit log) are **not implemented today**. Future commercial or server-service components, if released, will carry their own license terms and privacy notices, and will require an explicit opt-in before any data leaves a user's machine. Nothing in these Terms should be read as a commitment that such components will exist or that they will preserve the local-only posture of V1. ## 10. Privacy @@ -85,11 +82,11 @@ These terms are governed by the law of the maintainer's jurisdiction, except whe ## 14. Changes to these terms -These terms, the license model, and supporter-benefit framing may change for future versions of GhostMap. Changes do not retroactively remove personal, educational, evaluation/testing, or other non-commercial permission already granted for versions you obtained under the then-current license. Changes may affect future versions and any future commercial authorization. The product owner reserves the right to revise the license model — including the structure of allowed and prohibited use, the supporter benefits framework, and any future commercial licensing system — for future versions. +These terms, the license model, and supporter-benefit framing may change for future versions of GhostMap. Changes do not retroactively remove personal, educational, evaluation/testing, or other non-commercial permission already granted for versions you obtained under the then-current license. Changes may affect future versions and any future commercial authorization. The product owner reserves the right to revise the license model (including the structure of allowed and prohibited use, the supporter benefits framework, and any future commercial licensing system) for future versions. ## 15. Intellectual property -All intellectual property in GhostMap — the original source code, the Ghost-prefixed vocabulary, the ghost mark, documentation, screenshots, and product copy on this docs site and the marketing site — is owned by the GhostMap project owner. Nothing in these terms transfers ownership of GhostMap intellectual property to any user, supporter, or licensee. Permitted use under section 2 and any commercial license under section 5 grant only the use described in those sections; they do not transfer ownership. +All intellectual property in GhostMap (the original source code, the Ghost-prefixed vocabulary, the ghost mark, documentation, screenshots, and product copy on this docs site and the marketing site) is owned by the GhostMap project owner. Nothing in these terms transfers ownership of GhostMap intellectual property to any user, supporter, or licensee. Permitted use under section 2 and any commercial license under section 5 grant only the use described in those sections; they do not transfer ownership. ## 16. Contact diff --git a/docs/overview.md b/docs/overview.md new file mode 100644 index 0000000..a981c56 --- /dev/null +++ b/docs/overview.md @@ -0,0 +1,66 @@ +--- +id: overview +title: Overview +sidebar_label: Overview +slug: /overview +--- + +# Overview + +## What GhostMap is + +GhostMap is a VS Code extension that turns structured `@ghost` comments into a navigable map of your file: a semantic tree of classes, functions, methods, interfaces and anchors that live next to the code they describe. + +You write a comment like: + +```ts +class AuthService { + // @ghost description: validate jwt tokens | status: review + login() { + // ... + } + + // @ghost description: revoke session | status: done + logout() { + // ... + } +} +``` + +GhostMap renders it in the side panel as: + +```text +AuthService +├── login (review): validate jwt tokens +└── logout (done): revoke session +``` + +No external task tracker, no extra config. The tree rebuilds itself as you type. + +## Where to go next + +- [Start](/): docs entry page. +- [Install](/install): current install reality (local VSIX), planned channels. +- [Requirements](/get-started/requirements): VS Code version, supported languages, tier matrix. +- [First 5 minutes](/get-started/first-5-minutes): your first `@ghost` walkthrough. +- [Guide / Philosophy](/guide/philosophy): symbols, anchors, ownership. +- [Syntax reference](/reference/syntax): every valid `@ghost` form. +- [Settings](/reference/settings): every `ghostmap.*` setting. +- [Architecture](/architecture/v1): the pipeline behind the tree. +- [Project status](/status/project-status): known limits. +- [Roadmap: v2 vision](/roadmap/v2): future direction. +- [FAQ](/faq), [Troubleshooting](/troubleshooting), [Glossary](/glossary). +- [Legal & Support](/legal-support): license summary, third-party notices, contact. +- [Changelog](/changelog): release history. + +## Project status (short) + +- Version 0.5.0, pre-release. +- VS Code engine `^1.85.0`. +- 19 languages supported across quality tiers. +- Distribution today: locally built VSIX, requested by email. +- Planned channels: GitHub Releases (post-tag), VS Code Marketplace, Open VSX. None of these are active yet: see [Install](/install) and [Project status](/status/project-status). + +## License (short) + +GhostMap is source-available under the **GhostMap Free Non-Commercial License**. Personal, educational, and evaluation use is free. Commercial use needs a written license. The `LICENSE` file shipped with the extension is the authoritative legal document. See [Legal & Support](/legal-support). diff --git a/docs/reference/diagnostics.md b/docs/reference/diagnostics.md index 11efa80..497d979 100644 --- a/docs/reference/diagnostics.md +++ b/docs/reference/diagnostics.md @@ -6,26 +6,26 @@ sidebar_label: Diagnostics # Ghost Diagnostics -GhostMap muestra advertencias e información directamente en el editor cuando detecta anotaciones malformadas o ambiguas. +GhostMap shows warnings and information directly in the editor when it detects malformed or ambiguous annotations. -## Tabla de diagnósticos +## Diagnostics table -| Código | Severidad | Cuándo aparece | +| Code | Severity | When it appears | |---|---|---| -| `ghost-unclosed-range` | Warning | Un `@ghost #nombre start` nunca recibió su `@ghost end` correspondiente. Se degrada a Point Anchor (no arrastra símbolos posteriores como hijos). | -| `ghost-unexpected-end` | Warning | Existe un `@ghost end` sin apertura (`start`) previa. | -| `ghost-malformed-syntax` | Warning | Sintaxis híbrida no reconocida tras `@ghost` (ver [Reglas gramaticales](/reference/sintaxis#45-reglas-gramaticales-y-errores-comunes)). Incluye sugerencia de los dos quick fixes correspondientes. | -| `ghost-detached-symbol` | Information | Un Contextual Anchor no encontró ningún símbolo dentro del radio de ownership. | -| `ghost-ambiguous-ownership` | Information | Un Contextual Anchor tiene múltiples símbolos candidatos igual de cercanos; se listan los nombres. | +| `ghost-unclosed-range` | Warning | A `@ghost #name start` never received its matching `@ghost end`. It degrades to a Point Anchor (does not drag later symbols as children). | +| `ghost-unexpected-end` | Warning | A `@ghost end` exists with no opening (`start`) before it. | +| `ghost-malformed-syntax` | Warning | Unrecognized hybrid syntax after `@ghost` (see [Grammar rules](/reference/syntax#45-grammar-rules-and-common-errors)). Includes a suggestion for the two matching quick fixes. | +| `ghost-detached-symbol` | Information | A Contextual Anchor found no symbol inside the ownership radius. | +| `ghost-ambiguous-ownership` | Information | A Contextual Anchor has several candidates equally close; their names are listed. | -## Code Actions disponibles +## Available Code Actions -- **"Add @ghost annotation"** — sobre una línea `function`/`class` sin anotación previa, inserta una línea `// @ghost description: | status: todo` justo arriba. -- **"Convert to semantic anchor: @ghost #token"** / **"Convert to contextual anchor: @ghost description: …"** — sobre sintaxis híbrida malformada. -- **Fix de clave mal escrita** (`statu:` → `status:`) cuando la clave contiene "stat"/"statu" pero no es exactamente `status` o `description`. -- **Fix de valor de status inválido** — sugiere el status soportado más parecido (por prefijo) o `todo`. -- **"Add #anchor name"** — sobre una línea `@ghost` sin `#`, `start` ni `end` que no es el anchor más cercano a ningún símbolo, sugiere agregar `#name`. +- **"Add @ghost annotation"**: on a `function`/`class` line with no previous annotation, inserts `// @ghost description: | status: todo` just above it. +- **"Convert to semantic anchor: @ghost #token"** / **"Convert to contextual anchor: @ghost description: ..."**: on malformed hybrid syntax. +- **Misspelled-key fix** (`statu:` to `status:`) when the key contains "stat"/"statu" but is not exactly `status` or `description`. +- **Invalid status value fix**: suggests the closest supported status (by prefix) or `todo`. +- **"Add #anchor name"**: on a `@ghost` line without `#`, `start`, or `end` that is not the closest anchor to any symbol, suggests adding `#name`. -## Siguiente paso +## Next step -Continúa con **[Settings](/reference/settings)** para ajustar el comportamiento de GhostMap a tu proyecto. +Continue with **[Settings](/reference/settings)** to tune GhostMap's behavior for your project. diff --git a/docs/reference/ghost-tree.md b/docs/reference/ghost-tree.md index 5cf7c8d..977795a 100644 --- a/docs/reference/ghost-tree.md +++ b/docs/reference/ghost-tree.md @@ -6,20 +6,20 @@ sidebar_label: Ghost Tree # Ghost Tree -## Cómo se construye la jerarquía +## How the hierarchy is built -El árbol se construye por **contención de rangos**, no por nombres compuestos. +The tree is built by **range containment**, not by composed names. -**Regla de pertenencia:** el nodo A es padre de B si `A.start <= B.start` y `A.end > B.start` — es decir, B "nace" dentro del rango de A, aunque su cuerpo se extienda más allá. +**Containment rule:** node A is the parent of B if `A.start <= B.start` and `A.end > B.start`. That is, B "is born" inside A's range, even if its body extends further. -## Ejemplo combinando símbolos y anchors +## Example combining symbols and anchors ```ts -// @ghost #pagos start description: módulo de pagos v2 | status: in-progress +// @ghost #payments start description: payments module v2 | status: in-progress class PaymentService { - // @ghost description: falta manejar timeouts | status: todo + // @ghost description: handle timeouts | status: todo charge() {} refund() {} @@ -29,41 +29,41 @@ class PaymentService { ``` ```text -pagos (in-progress) — módulo de pagos v2 +payments (in-progress): payments module v2 └── PaymentService - ├── charge (todo) — falta manejar timeouts + ├── charge (todo): handle timeouts └── refund ``` -## Vista en VS Code +## VS Code view -El panel lateral "GhostMap" muestra el árbol con iconos por tipo de nodo: +The "GhostMap" side panel shows the tree with icons per node type: -- 🔵 Function/Method/Constructor → ícono de método (azul). -- 🟣 Class/Interface/Struct/Enum → ícono de clase (morado). -- 🟢 Anchor → ícono de bookmark (verde). -- ⚪ Nodo "de contexto" — visible solo porque un hijo coincide con un filtro/búsqueda activa → ícono atenuado con la etiqueta `(context)`. +- Function / Method / Constructor: method icon (blue). +- Class / Interface / Struct / Enum: class icon (purple). +- Anchor: bookmark icon (green). +- Context node (visible only because a child matches an active filter or search): dimmed icon with a `(context)` label. -Hacer clic en un nodo navega directamente a la línea correspondiente y resalta brevemente el rango. +Clicking a node navigates directly to the matching line and briefly highlights the range. -## Comandos y toolbar +## Commands and toolbar -| Botón / Comando | Etiqueta | Notas | +| Button / Command | Label | Notes | |---|---|---| -| Refrescar árbol | `Refresh` | Re-ejecuta el pipeline para el documento activo (sujeto a [Loading Policy](/architecture/loading-policy)). | -| Filtrar | `Filter` | Abre el menú de filtro por tipo o por status. | -| Reiniciar filtros | `Reset` | Limpia tipo, status y búsqueda activos. | -| Buscar | `Search` | Abre el input de búsqueda libre (nombre/descripción). | +| Refresh the tree | `Refresh` | Re-runs the pipeline for the active document (subject to [Loading Policy](/architecture/loading-policy)). | +| Filter | `Filter` | Opens the type or status filter menu. | +| Reset filters | `Reset` | Clears the active type, status, and search. | +| Search | `Search` | Opens the free search input (name or description). | -Todos los comandos aparecen en la paleta de comandos de VS Code agrupados bajo la categoría **GhostMap** (por ejemplo, "GhostMap: Refresh", "GhostMap: Filter"). +All commands appear in the VS Code command palette grouped under the **GhostMap** category (for example, "GhostMap: Refresh", "GhostMap: Filter"). -## Filtros y búsqueda +## Filters and search -- **Filtro por tipo:** `function` / `class` / `anchor` / Todos. -- **Filtro por status:** lista dinámica de los estados presentes en el proyecto, con conteo (`todo (5)`, `in-progress (2)`, etc.). El último filtro de status usado se recuerda entre sesiones. -- **Búsqueda libre:** filtra por nombre o por contenido de `description` (sin distinguir mayúsculas/minúsculas). -- **Visibilidad por burbuja:** si un hijo cumple el filtro/búsqueda, su(s) padre(s) permanecen visibles —marcados como "contexto"— aunque no cumplan el filtro por sí mismos. Así nunca se pierde la ubicación del resultado dentro del árbol. +- **Type filter:** `function` / `class` / `anchor` / All. +- **Status filter:** a dynamic list of the statuses present in the project, with counts (`todo (5)`, `in-progress (2)`, etc.). The last status filter used is remembered across sessions. +- **Free search:** filters by name or by `description` content (case-insensitive). +- **Bubble visibility:** if a child matches the filter or search, its parent(s) stay visible (marked as "context") even if they do not match on their own. The location of the result is never lost inside the tree. -## Siguiente paso +## Next step -Continúa con **[Diagnostics](/reference/diagnostics)** para ver qué advertencias puede mostrar GhostMap y cómo resolverlas. +Continue with **[Diagnostics](/reference/diagnostics)** to see the warnings GhostMap can show and how to fix them. diff --git a/docs/reference/performance.md b/docs/reference/performance.md new file mode 100644 index 0000000..21b81ce --- /dev/null +++ b/docs/reference/performance.md @@ -0,0 +1,90 @@ +--- +id: performance +title: Performance +sidebar_label: Performance +--- + +# Performance + +This page documents the system's real numbers in V1, how it behaves under different conditions, and what levers you have to tune it. + +## The Ghost Engine + +The **Ghost Engine** is the symbol-extraction stack. It runs in three steps in preference order: + +``` +LSP (language server) + → if unavailable or slow (> 800 ms): Tree-sitter WASM + → if no grammar is available: regex fallback +``` + +Each layer is faster and less precise than the previous one. In most cases LSP gives the best result. On small files with LSP active, the Ghost Engine short-circuits and skips Tree-sitter and regex completely (saves up to 1.2 s of WASM load). + +## Reference numbers + +| Scenario | Time | +|---|---| +| Open from Ghost Index (valid snapshot) | **< 50 ms** | +| Small file (< 500 lines) with LSP active | **200 to 600 ms** | +| 60k-line file, progressive scanner | **~33 ms** of pure scan | +| LSP cold start under normal conditions | **800 ms to 3 s** | +| LSP cold start under RAM pressure (80 to 90 percent) | **5 to 35 s** (GhostMap does not wait: it falls back at 800 ms) | + +> **Ghost Index is the key:** +> The most common scenario after the first open is always the first one: < 50 ms from snapshot. The first open of a file pays the extraction cost; every later open does not. + +## The progressive scanner (large files) + +For files of 50,000 lines or more, GhostMap uses a regex-based scanner that yields control to the VS Code event loop between batches: the editor does not freeze while it analyzes. + +- Batch size: 4,000 lines per iteration. +- The first 50 symbols are published to the tree before the full analysis finishes. The tree appears quickly and fills in. +- The in-progress tree updates every 250 ms (publish coalescer), not on every symbol found. This avoids panel flicker. + +**Measured on a C++ 60k-line file:** pure scan of ~33 ms of effective CPU time (vs ~19.5 s before the `setTimeout` overhead was removed). + +## Behavior under RAM pressure + +With the system at 80 to 90 percent RAM in use: + +- The language server can take 5 to 30 s to respond. GhostMap has an **800 ms** timeout: if the LSP does not answer, it drops to Tree-sitter + regex and publishes the tree without waiting. +- The **status badge** in the panel header shows `[loading]`, `[cached]`, `[stale-cache]`, or `[discarded:...]` so you can see exactly what is happening without opening the console. +- The **Ghost Index** mitigates the problem: if the file was analyzed before, the tree loads from the snapshot in < 50 ms without touching the LSP. + +## Tab switching + +Switching files quickly (< 150 ms between switches) triggers a backpressure mechanism: + +- GhostMap waits 200 ms before starting the refresh of the destination file. +- Files of 50 lines or fewer (`ghostmap.loading.tinyLineThreshold`) ignore this delay. They appear instantly. +- If the user keeps switching tabs during the delay, only the last destination is processed. The intermediate ones are dropped. + +This prevents opening 10 tabs in a row from queuing 10 full analyses. + +## Watchdog + +If the tree does not update within 1 second after a file switch, GhostMap's watchdog detects the state and fires a recovery refresh, but only if a refresh is not already in flight for that file. This prevents double LSP calls under stress. + +## Limits and how to tune them + +All performance limits are configurable. The full table is in [Settings](/reference/settings); the most relevant ones: + +| Setting | Default | When to adjust | +|---|---|---| +| `ghostmap.loading.maxAutoLines` | `60000` | If you regularly work with files larger than 60k lines. | +| `ghostmap.loading.maxAutoBytes` | `10000000` (10 MB) | If you have very heavy generated files. | +| `ghostmap.loading.tinyLineThreshold` | `50` | Raise to 200+ if you want more files to skip backpressure. | +| `ghostmap.loading.allowManualLargeFileRefresh` | `false` | Turn on if you want manual refresh on large files. | +| `ghostmap.backgroundIndex.enabled` | `false` | Turn on if you have RAM to spare and want open tabs pre-indexed on idle. | + +## Observability + +If something feels slow and you want to understand why, turn on structured logging: + +```json +"ghostmap.performanceLogging": true +``` + +Events go to `Output → GhostMap` in VS Code: per-refresh timings, progressive scanner batches, LSP warm-up, watchdog recoveries, and more. + +Combine with the status badge in the panel header for a complete picture without opening the console. diff --git a/docs/reference/rendimiento.md b/docs/reference/rendimiento.md deleted file mode 100644 index b8e7435..0000000 --- a/docs/reference/rendimiento.md +++ /dev/null @@ -1,91 +0,0 @@ ---- -id: rendimiento -title: Rendimiento -sidebar_label: Rendimiento ---- - -# Rendimiento - -Esta página documenta los números reales del sistema en V1, cómo se comporta bajo distintas condiciones, y qué palancas tienes para ajustarlo. - -## El Ghost Engine - -El **Ghost Engine** es la pila de extracción de símbolos. Ejecuta en tres pasos en orden de preferencia: - -``` -LSP (language server) - → si no disponible o lento (> 800 ms): Tree-sitter WASM - → si no hay gramática disponible: regex fallback -``` - -Cada capa es más rápida y menos precisa que la anterior. En la mayoría de los casos, LSP da el mejor resultado. En archivos pequeños con LSP activo, el Ghost Engine hace un cortocircuito y omite Tree-sitter y regex completamente (ahorra hasta 1.2 s de carga de WASM). - -## Números de referencia - -| Escenario | Tiempo | -|---|---| -| Apertura con Ghost Index (snapshot válido) | **< 50 ms** | -| Archivo pequeño (< 500 líneas) con LSP activo | **200 – 600 ms** | -| Archivo 60k líneas, scanner progresivo | **~33 ms** de scan puro | -| LSP cold start en condiciones normales | **800 ms – 3 s** | -| LSP cold start bajo presión de RAM (80–90%) | **5 – 35 s** (GhostMap no espera — cae al fallback a los 800 ms) | - -:::tip Ghost Index es la clave -El escenario más común después de la primera apertura es siempre el primero: < 50 ms desde snapshot. La primera apertura de un archivo paga el costo de extracción; todas las siguientes no. -::: - -## El scanner progresivo (archivos grandes) - -Para archivos de 50,000 líneas o más, GhostMap usa un scanner basado en regex que cede el control al event loop de VS Code entre lotes — el editor no se congela mientras analiza. - -- Tamaño de lote: 4,000 líneas por iteración. -- Primeros 50 símbolos se publican en el árbol antes de terminar el análisis completo. El árbol aparece rápido y se va completando. -- El árbol en construcción se actualiza cada 250 ms (publish coalescer), no en cada símbolo encontrado. Esto evita que el panel parpadee. - -**Resultado medido en C++ 60k líneas:** scan puro de ~33 ms de tiempo de CPU efectivo (vs ~19.5 s del overhead anterior a la optimización con `setTimeout`). - -## Comportamiento bajo presión de RAM - -Con el sistema al 80–90% de RAM en uso: - -- El language server puede tardar 5–30 s en responder. GhostMap tiene un timeout de **800 ms**: si el LSP no contesta, cae a Tree-sitter + regex y publica el árbol sin esperar más. -- El **badge de estado** en el header del panel muestra `[loading]`, `[cached]`, `[stale-cache]` o `[discarded:...]` para que sepas exactamente qué está pasando sin tener que abrir la consola. -- El **Ghost Index** mitiga el problema: si el archivo ya fue analizado antes, el árbol se carga desde el snapshot en < 50 ms, sin tocar el LSP. - -## Tab switching - -Cambiar de archivo rápido (< 150 ms entre switches) activa un mecanismo de backpressure: - -- GhostMap espera 200 ms antes de iniciar el refresh del archivo destino. -- Archivos de ≤ 50 líneas (`ghostmap.loading.tinyLineThreshold`) ignoran este retraso. Aparecen al instante. -- Si el usuario sigue cambiando tabs durante ese delay, solo se procesa el último destino. Los intermedios se descartan. - -Esto evita que abrir 10 tabs seguidos encole 10 análisis completos. - -## Watchdog - -Si el árbol no se actualiza en 1 segundo después de cambiar de archivo, GhostMap tiene un watchdog que detecta el estado y lanza un refresh de recuperación, pero solo si no hay ya un refresh en vuelo para ese mismo archivo. Esto previene doubles LSP calls bajo estrés. - -## Límites y cómo ajustarlos - -Todos los límites de rendimiento son configurables. La tabla completa está en [Settings](/reference/settings); los más relevantes: - -| Setting | Default | Cuándo ajustar | -|---|---|---| -| `ghostmap.loading.maxAutoLines` | `60000` | Si trabajas con archivos > 60k líneas regularmente. | -| `ghostmap.loading.maxAutoBytes` | `10000000` (10 MB) | Si tienes archivos generados muy pesados. | -| `ghostmap.loading.tinyLineThreshold` | `50` | Sube a 200+ si quieres que más archivos ignoren el backpressure. | -| `ghostmap.loading.allowManualLargeFileRefresh` | `false` | Activa si quieres poder refrescar archivos grandes con el botón manual. | -| `ghostmap.backgroundIndex.enabled` | `false` | Activa si tienes RAM de sobra y quieres pre-indexar tabs abiertas en idle. | - -## Observabilidad - -Si algo se siente lento y quieres entender por qué, activa el logging estructurado: - -```json -"ghostmap.performanceLogging": true -``` - -Los eventos se publican en `Output → GhostMap` en VS Code: tiempos de cada refresh, batch del scanner progresivo, LSP warm-up, watchdog recoveries, y más. - -Combínalo con el badge de estado en el header del panel para tener una imagen completa sin necesidad de abrir la consola. diff --git a/docs/reference/settings.md b/docs/reference/settings.md index 94e2062..8bbf233 100644 --- a/docs/reference/settings.md +++ b/docs/reference/settings.md @@ -1,27 +1,27 @@ --- id: settings -title: Configuración / Settings +title: Settings sidebar_label: Settings --- -# Configuración +# Settings -GhostMap funciona con valores por defecto razonables. Puedes ajustar cualquiera de estos settings desde `settings.json` o desde la UI de Settings de VS Code (busca "GhostMap"). +GhostMap runs on sensible defaults. You can adjust any of these settings from `settings.json` or from the VS Code Settings UI (search for "GhostMap"). -## Comportamiento de anotaciones `@ghost` +## `@ghost` annotation behavior ### `ghostmap.ownershipRadius` - **Default**: `5` -- **Rango**: `1` a `20` -- Número de líneas alrededor de una anotación `@ghost` en las que GhostMap busca un símbolo cercano para enlazar la descripción y el status. Se usa también en los diagnósticos `detached` y `ambiguous` y en el autocompletado contextual de `gh`+Tab. -- Súbelo si escribes comentarios largos antes de una función. Bájalo si los anchors se enganchan al símbolo equivocado. -- Ver [Ownership Radius](/guide/ownership-radius). +- **Range**: `1` to `20` +- Number of lines around a `@ghost` annotation in which GhostMap looks for a nearby symbol to attach the description and status. Also used in the `detached` and `ambiguous` diagnostics and in the contextual `gh`+Tab completion. +- Raise it if you write long comments before a function. Lower it if anchors latch onto the wrong symbol. +- See [Ownership Radius](/guide/ownership-radius). ### `ghostmap.statusColors` -- **Default**: un mapa con `done`, `complete`, `completed`, `todo`, `pending`, `in-progress`, `progress`, `review`, `testing`, `blocked`, `error`, `critical` enlazados a los colores de chart del tema activo (verde, amarillo, azul, morado, rojo). -- Permite añadir o redefinir el color de cualquier status custom. Las claves que no estén en el mapa se renderizan sin color de override. +- **Default**: a map of `done`, `complete`, `completed`, `todo`, `pending`, `in-progress`, `progress`, `review`, `testing`, `blocked`, `error`, `critical` to the active theme's chart colors (green, yellow, blue, purple, red). +- Lets you add or redefine the color of any custom status. Keys not in the map render without color override. ```json "ghostmap.statusColors": { @@ -30,65 +30,65 @@ GhostMap funciona con valores por defecto razonables. Puedes ajustar cualquiera } ``` -## Loading policy (presupuesto de archivos) +## Loading policy (file budget) ### `ghostmap.loading.maxAutoLines` - **Default**: `60000` -- **Mínimo**: `100` -- Límite de líneas por archivo para el refresco automático. Archivos más grandes se marcan como `skipped` para mantener el editor responsivo. El scanner progresivo de GhostMap evalúa una regex por línea por patrón, así que el costo crece linealmente. -- Súbelo si trabajas habitualmente con archivos generados de 100k+ líneas y tu máquina lo aguanta. -- Ver [Loading Policy](/architecture/loading-policy). +- **Minimum**: `100` +- Per-file line cap for the automatic refresh. Larger files are flagged as `skipped` to keep the editor responsive. GhostMap's progressive scanner evaluates one regex per line per pattern, so the cost grows linearly. +- Raise it if you regularly work with generated files of 100k+ lines and your machine can take it. +- See [Loading Policy](/architecture/loading-policy). ### `ghostmap.loading.maxAutoBytes` - **Default**: `10000000` (10 MB) -- **Mínimo**: `1024` -- Límite de tamaño en bytes para el refresco automático. Cubre el caso donde un archivo no es enorme en líneas pero sí en bytes (minified JS, JSON grande). El fingerprint SHA-256 de un archivo de varios MB toma cientos de milisegundos por sí solo. +- **Minimum**: `1024` +- Per-file byte cap for the automatic refresh. Covers the case where a file is not huge in lines but is huge in bytes (minified JS, large JSON). The SHA-256 fingerprint of a multi-MB file alone takes hundreds of milliseconds. ### `ghostmap.loading.tinyLineThreshold` - **Default**: `50` -- **Rango**: `0` a `500` -- Archivos con esta cantidad de líneas o menos saltan la ventana de 200 ms de backpressure por cambio rápido de tabs (aparecen al instante en el árbol) y se evalúan también para detectar si están vacíos o solo contienen espacios. -- Súbelo a 200+ si quieres que más archivos pequeños eviten el backpressure (tradeoff: menos coalescencia entre cambios rápidos consecutivos). +- **Range**: `0` to `500` +- Files with this many lines or fewer skip the 200 ms backpressure window for fast tab switches (they appear instantly in the tree) and are also evaluated to detect if they are empty or whitespace-only. +- Raise to 200+ if you want more small files to skip backpressure (tradeoff: less coalescing across rapid consecutive switches). ### `ghostmap.loading.allowManualLargeFileRefresh` - **Default**: `false` -- Cuando está en `true`, el comando manual **GhostMap: Refresh** ignora `maxAutoLines` y `maxAutoBytes`. Útil para investigar puntualmente un archivo generado sin tener que subir el presupuesto global. +- When `true`, the manual command **GhostMap: Refresh** ignores `maxAutoLines` and `maxAutoBytes`. Useful for occasionally inspecting a generated file without raising the global budget. -## Indexación en segundo plano +## Background indexing ### `ghostmap.backgroundIndex.enabled` - **Default**: `false` -- Activa una cola que escanea de forma oportunista archivos visibles y abiertos durante los momentos de inactividad. La concurrencia está fijada en 1 y la cola se limita a 128 entradas. -- Está desactivada por defecto porque en máquinas bajo presión puede competir con el language server activo. Actívala si tienes RAM y CPU de sobra y quieres que las tabs a las que cambies tengan el árbol ya caliente. +- Turns on a queue that opportunistically scans visible and open files during idle moments. Concurrency is fixed at 1 and the queue is capped at 128 entries. +- Off by default because on memory-pressured machines it can compete with the active language server. Turn it on if you have RAM and CPU to spare and want tabs you switch to be warm. -## Observabilidad +## Observability ### `ghostmap.performanceLogging` - **Default**: `false` -- Activa logging estructurado de eventos de activación y refresh en la consola del Extension Host. Los eventos aparecen en `Output → GhostMap`: tiempos de cada refresh, batches del scanner progresivo, warm-up del LSP, recuperaciones del watchdog, eventos de la cola de background, etc. -- Pensado para debugging puntual cuando algo se siente lento. Combínalo con el badge de estado del header del panel para una imagen completa. +- Enables structured logging of activation and refresh events in the Extension Host console. Events go to `Output → GhostMap`: timings per refresh, progressive scanner batches, LSP warm-up, watchdog recoveries, background queue events, and more. +- Intended for occasional debugging when something feels slow. Combine with the status badge in the panel header for a full picture. ```json "ghostmap.performanceLogging": true ``` -## Comandos contribuidos +## Contributed commands -| Comando (Command Palette) | Para qué sirve | +| Command (Command Palette) | What it does | |---|---| -| `GhostMap: Refresh` | Fuerza un recálculo del documento activo. Con `allowManualLargeFileRefresh: true` puede saltarse los límites de tamaño. | -| `GhostMap: Filter` | Filtra el árbol por status (o por tipo). | -| `GhostMap: Search` | Filtra el árbol por substring de nombre/descripción. | -| `GhostMap: Reset` | Limpia filtros y búsqueda activos. | +| `GhostMap: Refresh` | Forces a recompute of the active document. With `allowManualLargeFileRefresh: true` it can bypass the size limits. | +| `GhostMap: Filter` | Filters the tree by status (or by type). | +| `GhostMap: Search` | Filters the tree by name/description substring. | +| `GhostMap: Reset` | Clears active filters and search. | -Todos los comandos aparecen también en la toolbar del panel **GhostMap**. +All commands also appear on the **GhostMap** panel toolbar. -## Siguiente paso +## Next step -Si quieres entender cómo funciona el pipeline por dentro, continúa con **[Arquitectura v1](/architecture/arquitectura-v1)**. +If you want to understand how the pipeline works under the hood, continue with **[Architecture v1](/architecture/v1)**. diff --git a/docs/reference/sintaxis.md b/docs/reference/sintaxis.md deleted file mode 100644 index eb48268..0000000 --- a/docs/reference/sintaxis.md +++ /dev/null @@ -1,101 +0,0 @@ ---- -id: sintaxis -title: 'Sintaxis: anotaciones @ghost' -sidebar_label: Sintaxis ---- - -# Sintaxis: anotaciones `@ghost` - -Hay tres formas válidas de escribir una anotación `@ghost`. Las tres usan la misma gramática base; lo que cambia es la presencia de `#nombre` y de `start`/`end`. - -## 4.1 Point Anchor (con nombre) - -```ts -// @ghost #nombre description: ... | status: ... -``` - -```python -# @ghost #nombre description: ... | status: ... -``` - -Crea un nodo propio en el árbol con identidad (`#nombre`). Ver [Semantic Anchor](/guide/semantic-anchor). - -## 4.2 Contextual Anchor (sin nombre) - -```ts -// @ghost description: ... | status: ... -``` - -```python -# @ghost description: ... | status: ... -``` - -No crea un nodo propio: se adjunta al símbolo más cercano dentro del [radio de ownership](/guide/ownership-radius). Ver [Contextual Anchor](/guide/contextual-anchor). - -## 4.3 Range Anchor - -```ts -// @ghost #nombre start description: ... | status: ... - -...código... - -// @ghost end -``` - -```python -# @ghost #nombre start description: ... | status: ... - -...código... - -# @ghost end -``` - -Agrupa una sección completa de código bajo un nodo. Ver [Range Anchor](/guide/range-anchor). - -## 4.4 Snippets disponibles - -GhostMap incluye snippets para crear cada tipo de anotación rápidamente: - -| Prefijo | Lenguajes | Resultado | -|---|---|---| -| `gh` | JS/TS/TSX/C/C++/Java/Go/PHP/C#/Rust/Kotlin/Swift/Scala/Groovy/Solidity (comentario `//`) | Point Anchor con nombre | -| `gw` | mismos | Contextual Anchor | -| `gr` | mismos | Range Anchor | -| `gl` | Python/Ruby/Elixir/Shell (comentario `#`) | Point Anchor con nombre | -| `gxl` | mismos | Contextual Anchor | -| `gxr` | mismos | Range Anchor | - -### Autocompletado contextual inteligente - -Escribir `gh` seguido de **Tab** directamente sobre una línea vacía activa un autocompletado que decide el tipo de anotación según el contexto: - -- Si hay un símbolo cercano dentro del radio de ownership → sugiere `// @ghost description: ... | status: todo` (Contextual). -- Si no hay símbolo cercano → sugiere `// @ghost #name description: ... | status: todo` (Semantic). -- Si hay **varios** candidatos igual de cercanos → sugiere primero el más cercano como contextual, luego ofrece la opción semántica (para evitar ambigüedad) y una opción contextual por cada candidato adicional. - -:::note -El autocompletado solo sugiere símbolos definidos **más abajo** en el archivo, dentro del rango de ownership configurado. -::: - -## 4.5 Reglas gramaticales y errores comunes - -- La línea debe empezar (ignorando espacios) con el prefijo de comentario del lenguaje (`//` o `#`), y debe haber un espacio después: `// @ghost ...` es válido, `//@ghost ...` **no** lo es. -- Después de `@ghost ` debe venir una de estas formas: - - `#nombre ...` - - `end` - - `start ...` - - `description: ...` - - `status: ...` -- Cualquier otra palabra suelta después de `@ghost` (por ejemplo `// @ghost revisar_pagos`) se considera **sintaxis híbrida malformada** y genera un diagnóstico de advertencia con dos quick fixes: - 1. Convertir a Semantic Anchor → `// @ghost #revisar_pagos` - 2. Convertir a Contextual Anchor → `// @ghost description: revisar_pagos` - -### Solo comentarios de línea - -En V1, un Anchor solo es válido si está escrito como **comentario de línea**: `// @ghost ...` o `# @ghost ...`. - -Comentarios de bloque o JSDoc (`/* @ghost ... */`, `/** @ghost ... */`) **no son evidencia válida de anchor en V1** y son ignorados por el parser. Si un `@ghost` dentro de un bloque `/** ... */` no aparece en el árbol, este es el comportamiento esperado — el soporte para comentarios de bloque podría llegar en una versión futura. - -## Siguiente paso - -Continúa con **[Ghost Tree](/reference/ghost-tree)** para ver cómo se construye la jerarquía y qué comandos están disponibles en VS Code. diff --git a/docs/reference/syntax.md b/docs/reference/syntax.md new file mode 100644 index 0000000..03c1512 --- /dev/null +++ b/docs/reference/syntax.md @@ -0,0 +1,102 @@ +--- +id: syntax +title: 'Syntax: @ghost annotations' +sidebar_label: Syntax +--- + +# Syntax: `@ghost` annotations + +There are three valid ways to write a `@ghost` annotation. All three use the same base grammar; what changes is the presence of `#name` and of `start`/`end`. + +## 4.1 Point Anchor (named) + +```ts +// @ghost #name description: ... | status: ... +``` + +```python +# @ghost #name description: ... | status: ... +``` + +Creates its own node in the tree with identity (`#name`). See [Semantic Anchor](/guide/semantic-anchor). + +## 4.2 Contextual Anchor (unnamed) + +```ts +// @ghost description: ... | status: ... +``` + +```python +# @ghost description: ... | status: ... +``` + +Does not create its own node: it attaches to the closest symbol within the [ownership radius](/guide/ownership-radius). See [Contextual Anchor](/guide/contextual-anchor). + +## 4.3 Range Anchor + +```ts +// @ghost #name start description: ... | status: ... + +...code... + +// @ghost end +``` + +```python +# @ghost #name start description: ... | status: ... + +...code... + +# @ghost end +``` + +Groups a whole code section under a single node. See [Range Anchor](/guide/range-anchor). + +## 4.4 Available snippets + +GhostMap ships snippets to create each annotation type quickly: + +Snippet availability only means the editor can insert the right comment syntax. It does not guarantee Ghost Tree symbol extraction for that language. + +| Prefix | Languages | Result | +|---|---|---| +| `gh` | JS/TS/TSX/C/C++/Java/Go/PHP/C#/Rust/Kotlin/Swift/Scala/Groovy/Solidity (line `//` comment) | Named Point Anchor | +| `gw` | same | Contextual Anchor | +| `gr` | same | Range Anchor | +| `gl` | Python/Ruby/Elixir/Shell (line `#` comment) | Named Point Anchor | +| `gxl` | same | Contextual Anchor | +| `gxr` | same | Range Anchor | + +### Smart contextual completion + +Typing `gh` then **Tab** on an empty line triggers a completion that picks the annotation type based on context: + +- If there is a nearby symbol within the ownership radius, it suggests `// @ghost description: ... | status: todo` (Contextual). +- If no symbol is nearby, it suggests `// @ghost #name description: ... | status: todo` (Semantic). +- If **several** candidates are equally close, it suggests the nearest one first as contextual, then offers the semantic option (to avoid ambiguity) and one contextual option per additional candidate. + +> **Note:** +> The completion only suggests symbols defined **below** in the file, within the configured ownership radius. + +## 4.5 Grammar rules and common errors + +- The line must start (ignoring whitespace) with the language's line-comment prefix (`//` or `#`), and there must be a space after it: `// @ghost ...` is valid, `//@ghost ...` is **not**. +- After `@ghost ` one of these forms must come: + - `#name ...` + - `end` + - `start ...` + - `description: ...` + - `status: ...` +- Any other loose word after `@ghost` (for example `// @ghost review_payments`) is considered **malformed hybrid syntax** and produces a warning diagnostic with two quick fixes: + 1. Convert to Semantic Anchor: `// @ghost #review_payments` + 2. Convert to Contextual Anchor: `// @ghost description: review_payments` + +### Line comments only + +In V1, an Anchor is only valid when written as a **line comment**: `// @ghost ...` or `# @ghost ...`. + +Block or JSDoc comments (`/* @ghost ... */`, `/** @ghost ... */`) are **not valid anchor evidence in V1** and are ignored by the parser. If a `@ghost` inside a `/** ... */` block does not appear in the tree, that is the expected behavior. Block comment support may arrive in a future version. + +## Next step + +Continue with **[Ghost Tree](/reference/ghost-tree)** to see how the hierarchy is built and which commands are available in VS Code. diff --git a/docs/roadmap/v2.md b/docs/roadmap/v2.md new file mode 100644 index 0000000..51ebc1f --- /dev/null +++ b/docs/roadmap/v2.md @@ -0,0 +1,80 @@ +--- +id: v2 +title: 'Roadmap: v2 vision' +sidebar_label: v2 vision +--- + +# Roadmap: v2 vision + +GhostMap Core (everything described in the rest of this documentation) is the V1 scope under the **GhostMap Free Non-Commercial License** (source-available, non-commercial use). What follows is the vision for future Enterprise capabilities, aimed at teams where this information needs to flow between the technical, operational, and management layers. Commercial use would require written authorization or a future licensing flow. + +> **Nothing in this section is shipped:** +> Everything described here (Ghost Index v2, Ghost Watcher, Ghost Threads, Ghost Graph, dashboards, AI explanations, Jira / Slack integrations, permissions / audit log) is **future direction**, not functionality available in V1 (0.5.x). What already works today is described in the rest of the documentation. +> +> Any future integration with server services will require its own disclosure in GhostMap's Privacy Policy and explicit consent before any data leaves your machine. For a current copy, write to [getghostmap@proton.me](mailto:getghostmap@proton.me). Nothing in this roadmap is a commitment on dates or final scope. + +## V2: workspace-wide indexing engine (planned) + +**State today (V1, 0.5.x):** the Ghost Tree is computed per active file. Every open file persists its snapshot to `.ghostmap/ghostmap.json` (see [Local State](/architecture/local-state)). That is a **per-document cache**, not a workspace index. There is no filesystem watcher and no background fingerprint validator (the earlier attempt was removed because it froze the Extension Host). + +**V2 direction (not shipped):** a persistent workspace-level index (the **Ghost Index v2**) built with JSON shards per top-level folder, kept up to date incrementally by a **Ghost Watcher** on the filesystem and validated out of band by a **Ghost Validator** in a worker thread (mtime prefilter + streaming SHA-256). The active-file refresh path (V1 responsiveness) is preserved: the V2 engine *layers in below*, it does not replace it. + +**Benefit if shipped:** opening any file in the workspace in milliseconds from the index, cross-file navigation, and a base for richer integrations. Until it ships, this is roadmap direction. + +**Potential index content:** files, symbols, anchors, metadata, resolved hierarchy, diagnostics, and, in the future, file-to-file relations / dependencies (the **Ghost Graph**, also known as the **Ghost Context Graph**). + +## Language expansion (separate workstream, planned) + +Independent of the V2 engine, a workstream exists to add roughly 20 more languages (Kotlin, Swift, Haskell, OCaml, Clojure, Lua, R, Bash, the SQL family, and others) on top of today's 19. **Not shipped.** The gate before any language is marked supported is: + +- reproducible packaging of the Tree-sitter / WASM grammars, +- query validity against the exact grammar version, +- a "load + sample query" smoke per grammar, +- nesting / icons / anchors fixtures in `test/matrix/`, +- and, where required, upstream PRs to the grammar. + +See [Disclaimer: Language pack expansion](/legal/disclaimer) and the "Language expansion" section in [Requirements](/get-started/requirements). + +> **Gate before future integrations:** +> Before publishing any integration with Jira, Slack, AI, dashboards, or server services, GhostMap has to close these points as product requirements, not as optional details: +> +> - **Permissions and roles:** which actions a person can initiate, which an agent can suggest, and which require explicit approval. +> - **Data model:** which fields are stored locally, which travel to external services, how they are versioned, and how they are deleted. +> - **Consent and privacy:** an updated notice, in-editor consent before transmitting data, and a clean split between V1 local-only and future connected capabilities. +> - **Recovery tests:** scenarios for revoked permissions, expired tokens, downed integrations, write conflicts, and safe rollback if an automation fails. +> +> Until those gates exist and are verified, the connected capabilities stay vision, not shipped product. + +## Pillar 1: Resume work without friction + +A dev finishes the day. The next day, they open VS Code and GhostMap. + +- **General dashboard** showing the state of every file and the Ghosts marked as urgent. +- **Urgency derived from Jira:** GhostMap connects to Jira, reads sprint timing for the active sprint and dependent sprints, and (with AI help) identifies relations and dependencies between sprints to flag urgent Ghosts (by their own due date or because they block another sprint). +- **Local chat in VS Code** that summarizes relevant conversations and context, and proposes what to do next based on urgency and scope. +- **One-click resume:** the dev jumps straight into the first urgent task, or continues exactly where they left off the day before. +- **Ghost Threads (per-block discussions):** any function, class, or block can have its own discussion, with a technical owner, QA, etc., with configurable permissions, including comments sent from Slack into a specific discussion. +- **Tangible progress in Jira:** when analyzing a Ghost or a large Range Anchor, GhostMap can propose a decomposition into Jira subtasks. Each subtask links back to its own Ghost in code, and as they are marked `done`, the parent task's progress updates proportionally and visibly. +- **Automated task closure:** when a Ghost's status flips to `done` (or equivalent), GhostMap can generate the matching commit, update Jira, notify QA/reviewer, and reflect the new state in real time for the whole team. +- **Permissions and traceability:** because this layer can generate commits, modify tickets, and create subtasks automatically, Enterprise includes role-based permissions and a record of which action was taken by a person and which by an AI agent. + +## Pillar 2: Understand someone else's code + +A new dev opens a file and does not know what is actually there. + +- **AI-generated explanations** for symbols without prior documentation. +- **Ghost Graph:** graphs showing relations between files, symbols, and dependencies (the **Ghost Context Graph** from the index). +- **Lists with context and urgency:** while viewing what functions / classes a file holds, the urgent items in that same file are also flagged. +- **Decision history:** direct access to past discussions about why a decision was made in that block of code. Information that today only lives in the head of whoever wrote it. +- **Non-mandatory structure suggestions:** GhostMap can suggest organizing the code (for example with Range Anchors) without forcing it. +- **In-editor notifications:** status changes or new relevant discussions arrive in VS Code, one click away from the exact spot. + +## Ghost Comments and retroactive documentation + +- **Ghost Comments (invisible ghosts):** in v2, Ghost information stops living as literal text in the file. VS Code shows it visually with decorations and CodeLens, without taking up lines in the source. The code stays clean and the information lives in the Ghost Index v2. +- **Conversion of existing comments:** `TODO`/`FIXME` style comments already in the code can be converted automatically into Ghost Metadata, reusing the same ownership resolution that exists today. +- **Automatic documentation of legacy code:** AI and graph analysis over code with no Ghosts at all, which proposes automatic Range Anchors and generates descriptions. Useful for "bootstrapping" the index on projects that never used GhostMap. + +## Next step + +For the current V1 state and known limits, continue with **[Project status](/status/project-status)**. diff --git a/docs/roadmap/vision-v2.md b/docs/roadmap/vision-v2.md deleted file mode 100644 index 49ff53f..0000000 --- a/docs/roadmap/vision-v2.md +++ /dev/null @@ -1,82 +0,0 @@ ---- -id: vision-v2 -title: 'Roadmap — Visión v2' -sidebar_label: Visión v2 ---- - -# Roadmap — Visión v2 - -GhostMap Core —todo lo descrito en el resto de esta documentación— es el alcance de V1 bajo la **GhostMap Free Non-Commercial License** (source-available, uso no comercial). Lo que sigue es la visión para futuras capacidades Enterprise, pensadas para equipos donde esta información necesita fluir entre la capa técnica, operativa y directiva; su uso comercial requeriría autorización por escrito o un futuro flujo de licencia. - -:::caution Nada de esta sección está publicado -Todo lo descrito en esta página — Ghost Index v2, Ghost Watcher, Ghost Threads, Ghost Graph, dashboards, explicaciones con IA, integraciones con Jira / Slack, permisos / audit log — es **dirección a futuro**, no funcionalidad disponible en V1 (0.5.x). Lo que ya funciona hoy se describe en el resto de la documentación. - -Cualquier integración con servicios de servidor que aparezca a futuro requerirá su propia divulgación en la Privacy Policy de GhostMap y un consentimiento explícito antes de enviar datos fuera de tu máquina (para una copia actual, escribir a [getghostmap@proton.me](mailto:getghostmap@proton.me)). Nada en este roadmap es una promesa de fecha ni de alcance final. -::: - -## V2 — motor de indexación workspace-wide (planificado) - -**Estado hoy (V1, 0.5.x):** el Ghost Tree se calcula por archivo activo. Cada archivo abierto persiste su snapshot en `.ghostmap/ghostmap.json` (ver [Local State](/architecture/local-state)). Eso es una **caché por documento**, no un índice de workspace. No hay file-system watcher ni validador de fingerprint en background (el intento anterior se quitó por congelar el Extension Host). - -**Dirección V2 (no publicada):** un índice persistente a nivel de workspace — el **Ghost Index v2** — construido con shards JSON por carpeta de primer nivel, mantenido actualizado incrementalmente por un **Ghost Watcher** sobre el filesystem y validado fuera de banda por un **Ghost Validator** en un worker thread (mtime prefilter + SHA-256 en stream). El path de refresh del archivo activo (la responsividad V1) se preserva: el motor V2 se *capa* por debajo, no lo reemplaza. - -**Beneficio si se publica:** apertura de cualquier archivo del workspace en milisegundos desde el índice, navegación cross-archivo y base para integraciones más ricas. Hasta que se publique, sigue siendo dirección de roadmap. - -**Contenido potencial del índice:** archivos, símbolos, anchors, metadata, jerarquía resuelta, diagnósticos y, a futuro, relaciones/dependencias entre archivos (el **Ghost Graph**, también conocido como **Ghost Context Graph**). - -## Expansión de lenguajes (workstream separado, planificado) - -Independiente del motor V2, hay un workstream para añadir ~20 lenguajes adicionales (Kotlin, Swift, Haskell, OCaml, Clojure, Lua, R, Bash, familia SQL, …) sobre la base actual de 19. **No está publicado.** El gate antes de marcar cualquier lenguaje como soportado es: - -- empaquetado reproducible de las gramáticas Tree-sitter / WASM, -- validez de queries contra la versión exacta de cada gramática, -- smoke de "load + sample query" por gramática, -- fixtures de nesting / iconos / anchors en `test/matrix/`, -- y, donde haga falta, PRs upstream a la gramática. - -Ver [Disclaimer → Language pack expansion](/legal/disclaimer) y la sección "Expansión de lenguajes" en [Requisitos](/get-started/requisitos). - -:::caution Gate antes de integraciones futuras -Antes de publicar cualquier integración con Jira, Slack, IA, dashboards o servicios de servidor, GhostMap necesita cerrar estos puntos como requisitos de producto, no como detalles opcionales: - -- **Permisos y roles:** qué acciones puede iniciar una persona, cuáles puede sugerir un agente, y cuáles requieren aprobación explícita. -- **Modelo de datos:** qué campos se guardan localmente, cuáles viajan a servicios externos, cómo se versionan y cómo se eliminan. -- **Consentimiento y privacidad:** aviso actualizado, consentimiento in-editor antes de transmitir datos, y separación clara entre V1 local-only y futuras capacidades conectadas. -- **Pruebas de recuperación:** escenarios de permisos revocados, tokens expirados, integraciones caídas, conflictos de escritura y rollback seguro si una automatización falla. - -Hasta que esos gates existan y estén verificados, las capacidades conectadas siguen siendo visión, no producto publicado. -::: - -## Pilar 1 — Retomar el trabajo sin fricción - -Un dev termina su día. Al siguiente, abre VS Code y GhostMap. - -- **Dashboard general** que muestra el estado de todos los archivos y los Ghosts marcados como urgentes. -- **Urgencia derivada de Jira:** GhostMap se conecta a Jira, obtiene los tiempos del sprint actual y de sprints dependientes, e identifica —con ayuda de IA— relaciones y dependencias entre sprints para marcar qué Ghosts son urgentes (por vencimiento propio o por bloquear otro sprint). -- **Chat local en VS Code** que resume conversaciones y contexto relevante, y propone qué hacer a continuación según urgencia y alcance. -- **Retomar contexto con un click:** el dev entra directo a la primera tarea urgente, o continúa exactamente donde lo dejó el día anterior. -- **Ghost Threads (discusiones por bloque de código):** cualquier función, clase o bloque puede tener su propia discusión, con responsable técnico, QA, etc., con permisos configurables, incluyendo comentarios enviados desde Slack hacia una discusión concreta. -- **Avance tangible en Jira:** al analizar un Ghost o un Range Anchor grande, GhostMap puede proponer una descomposición en subtareas dentro de Jira. Cada subtarea queda vinculada a su propio Ghost en el código, y a medida que se marcan como `done`, el avance de la tarea padre se actualiza de forma proporcional y visible. -- **Cierre de tarea automatizado:** al cambiar el status de un Ghost a `done` (o equivalente), GhostMap puede generar el commit correspondiente, actualizar Jira, notificar a QA/revisor, y reflejar el nuevo estado en tiempo real para todo el equipo. -- **Permisos y trazabilidad:** dado que esta capa puede generar commits, modificar tickets y crear subtareas automáticamente, Enterprise incluye control de permisos por rol y un registro de qué acción fue tomada por una persona y cuál por un agente de IA. - -## Pilar 2 — Entender código ajeno - -Un dev nuevo abre un archivo y no sabe qué hay realmente ahí. - -- **Explicaciones generadas por IA** sobre símbolos sin documentación previa. -- **Ghost Graph:** grafos que muestran relaciones entre archivos, símbolos y dependencias (el **Ghost Context Graph** desde el índice). -- **Listas con contexto y urgencia:** al ver qué funciones/clases hay en un archivo, también se indica qué está marcado como urgente ahí mismo. -- **Historial de decisiones:** acceso directo a las discusiones pasadas sobre por qué se tomó tal decisión en ese bloque de código. Información que hoy solo vive en la memoria de quien lo escribió. -- **Recomendaciones de estructura no obligatorias:** GhostMap puede sugerir organizar el código (por ejemplo, con Range Anchors) sin forzarlo. -- **Notificaciones in-editor:** cambios de estado o nuevas discusiones relevantes llegan directo a VS Code, con un click para ir al lugar exacto. - -## Ghost Comments y documentación retroactiva - -- **Ghost Comments (ghosts invisibles):** en v2, la información Ghost deja de vivir como texto literal en el archivo. VS Code la muestra visualmente con decoraciones y CodeLens, sin que ocupe líneas en el código fuente. El código permanece limpio, y la información vive en el Ghost Index v2. -- **Conversión de comentarios existentes:** comentarios tipo `TODO`/`FIXME` ya presentes en el código pueden convertirse automáticamente en Ghost Metadata, reutilizando la misma resolución de ownership que ya existe hoy. -- **Documentación automática de código legacy:** análisis con IA y grafos sobre código sin ningún Ghost, que propone Range Anchors automáticos y genera descripciones. Útil para "bootstrapear" el índice en proyectos que nunca usaron GhostMap. - -## Siguiente paso - -Para ver el estado actual de V1 y sus limitaciones conocidas, continúa con **[Estado del proyecto](/status/estado-del-proyecto)**. diff --git a/docs/status/estado-del-proyecto.md b/docs/status/estado-del-proyecto.md deleted file mode 100644 index e162f9f..0000000 --- a/docs/status/estado-del-proyecto.md +++ /dev/null @@ -1,49 +0,0 @@ ---- -id: estado-del-proyecto -title: Estado del proyecto -sidebar_label: Estado del proyecto ---- - -# Estado del proyecto - -:::caution V1 en pruebas finales -GhostMap V1 tiene buena cobertura de funcionalidad y pruebas automatizadas, pero todavía está pasando por validaciones manuales finales antes de un release amplio. Algunas funciones pueden comportarse de forma ligeramente distinta a lo descrito hasta que esas validaciones terminen. -::: - -## Estado de distribución - -| Canal | Estado | Notas | -| --- | --- | --- | -| VSIX local | ✅ Disponible | Camino principal hoy. Ver [Instalación](/get-started/instalacion) y [Instalar desde VSIX](/vsix-install). | -| GitHub Releases | 🧭 Planificado post-tag | Todavía no hay release público. Los releases futuros podrán adjuntar el VSIX después de crear un tag. | -| VS Code Marketplace | ⏳ Pendiente | El paquete todavía no tiene `publisher`; no hay listado oficial. | -| Open VSX (VSCodium, Cursor, etc.) | 🧭 Planificado | Puente recomendado para editores compatibles con Open VSX. Script `publish:open-vsx` (`ovsx publish`) ya preparado en `package.json`; pendientes namespace, token y primer publish. | - -Ningún cambio en estos canales afecta el código que ya tienes instalado por VSIX: una vez instalada, la extensión funciona localmente sin red. - -## Disponible hoy (v1) - -- Jerarquía symbol-first (símbolos primero, Ghosts después). -- Ownership contextual de Ghosts. -- Named anchors (`#nombre`). -- Range anchors. -- Diagnósticos (`unclosed-range`, `malformed-syntax`, `detached`, `ambiguous`, etc.). -- Hover con descripciones. -- Status tracking. -- Parsing multi-lenguaje (LSP, tree-sitter, regex fallback). -- Integración nativa en VS Code. - -## Limitaciones conocidas del MVP - -- **Archivos muy grandes:** archivos que superan las 60,000 líneas no se recalculan automáticamente para evitar bloquear el editor. Ver [Loading Policy](/architecture/loading-policy) para el detalle y cómo habilitar el refresco manual. -- **Rangos sin nombre:** un `@ghost ... start` sin `#nombre` es válido sintácticamente, pero no genera un nodo visible en el árbol. Ver [Range Anchor](/guide/range-anchor#importante-el-nombre-es-obligatorio-para-que-se-vea). -- **Solo comentarios de línea:** las anotaciones `@ghost` dentro de comentarios de bloque (`/* */`, `/** */`) no son reconocidas en V1. Ver [Sintaxis](/reference/sintaxis#solo-comentarios-de-línea). - -## Advertencias y dirección a futuro - -- **Idioma del producto (workstream separado):** GhostMap soporta 19 lenguajes hoy. Está planificada una expansión de ~20 lenguajes adicionales, bloqueada por empaquetado y procedencia de los WASM de Tree-sitter, validez de queries y cobertura de fixtures. Esos lenguajes no se anuncian como soportados hasta pasar ese gate. Ver [Requisitos](/get-started/requisitos) y [Disclaimer](/legal/disclaimer). -- **Motor V2 e integraciones Enterprise (no enviado):** la indexación a nivel de workspace, el Ghost Watcher y las integraciones Enterprise (Jira / Slack, Ghost Threads, Ghost Graph, dashboards, explicaciones con IA, permisos / audit log) están diseñadas pero **no publicadas**. Cualquier integración con servicios de servidor requeriría su propio aviso claro de privacidad y consentimiento explícito antes de salir. Ver [Roadmap — Visión v2](/roadmap/vision-v2); para una copia de la Privacy Policy vigente, escribir a [getghostmap@proton.me](mailto:getghostmap@proton.me). - -## Próximos pasos - -Ver **[Roadmap — Visión v2](/roadmap/vision-v2)** para la dirección a más largo plazo del proyecto. diff --git a/docs/status/project-status.md b/docs/status/project-status.md new file mode 100644 index 0000000..fba9bee --- /dev/null +++ b/docs/status/project-status.md @@ -0,0 +1,48 @@ +--- +id: project-status +title: Project status +sidebar_label: Project status +--- + +# Project status + +> **V1 in final testing:** +> GhostMap V1 has good functional and test coverage, but is still going through final manual validation before a wider release. Some functions may behave slightly differently from the description until those validations are finished. + +## Distribution status + +| Channel | Status | Notes | +| --- | --- | --- | +| Local VSIX | Available | Main path today. See [Install](/install) and [Install from VSIX](/vsix-install). | +| GitHub Releases | Planned post-tag | No public release yet. Future releases can attach the VSIX after a tag is created. | +| VS Code Marketplace | Pending | The package does not have a `publisher` yet; there is no official listing. | +| Open VSX (VSCodium, Cursor, etc.) | Planned | Recommended bridge for Open-VSX-compatible editors. The `publish:open-vsx` script (`ovsx publish`) is already prepared in `package.json`; namespace, token, and first publish are pending. | + +No change in these channels affects code you already have installed via VSIX: once installed, the extension runs locally with no network access. + +## Available today (v1) + +- Symbol-first hierarchy (symbols first, Ghosts after). +- Contextual Ghost ownership. +- Named anchors (`#name`). +- Range anchors. +- Diagnostics (`unclosed-range`, `malformed-syntax`, `detached`, `ambiguous`, etc.). +- Hover with descriptions. +- Status tracking. +- Multi-language parsing (LSP, Tree-sitter, regex fallback). +- Native VS Code integration. + +## Known MVP limitations + +- **Very large files:** files over 60,000 lines are not recomputed automatically to avoid blocking the editor. See [Loading Policy](/architecture/loading-policy) for the detail and how to enable manual refresh. +- **Unnamed ranges:** a `@ghost ... start` without `#name` is syntactically valid, but does not produce a visible node in the tree. See [Range Anchor](/guide/range-anchor#important-the-name-is-required-for-the-range-to-show). +- **Line comments only:** `@ghost` annotations inside block comments (`/* */`, `/** */`) are not recognized in V1. See [Syntax: line comments only](/reference/syntax#line-comments-only). + +## Warnings and future direction + +- **Project languages (separate workstream):** GhostMap supports 19 languages today. An expansion of roughly 20 more is planned, blocked by Tree-sitter WASM packaging and provenance, query validity, and fixture coverage. Those languages are not announced as supported until they pass that gate. See [Requirements](/get-started/requirements) and [Disclaimer](/legal/disclaimer). +- **V2 engine and Enterprise integrations (not shipped):** workspace-level indexing, the Ghost Watcher, and Enterprise integrations (Jira / Slack, Ghost Threads, Ghost Graph, dashboards, AI explanations, permissions / audit log) are designed but **not shipped**. Any integration with server services would need its own clear privacy notice and explicit consent before leaving. See [Roadmap: v2 vision](/roadmap/v2). For a copy of the active Privacy Policy, write to [getghostmap@proton.me](mailto:getghostmap@proton.me). + +## Next steps + +See **[Roadmap: v2 vision](/roadmap/v2)** for the longer-term direction. diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md index d77fbb3..f656066 100644 --- a/docs/troubleshooting.md +++ b/docs/troubleshooting.md @@ -1,80 +1,80 @@ --- id: troubleshooting -title: Solución de problemas -sidebar_label: Solución de problemas +title: Troubleshooting +sidebar_label: Troubleshooting --- -# Solución de problemas +# Troubleshooting -Síntomas comunes, qué los causa y cómo confirmarlo. +Common symptoms, what causes them, and how to confirm it. -## El panel GhostMap está vacío +## The GhostMap panel is empty -**Causa más probable:** el archivo activo no es un lenguaje soportado, o no contiene símbolos detectables (archivo de configuración, JSON puro, etc.). +**Most likely cause:** the active file is not a supported language, or it has no detectable symbols (config file, plain JSON, etc.). -**Confirmación:** -1. Mira la barra de estado de VS Code, esquina inferior derecha: indica el Language ID. -2. Compara contra la matriz de lenguajes en [Symbol](/guide/symbol). -3. Abre otro archivo claramente soportado (por ejemplo un `.ts`). Si ahí sí ves el árbol, el problema era el archivo original. +**Confirm:** +1. Look at the VS Code status bar, lower right corner: it shows the Language ID. +2. Compare against the language matrix in [Symbol](/guide/symbol). +3. Open another clearly supported file (for example a `.ts`). If you see the tree there, the original file was the problem. -**Otras causas posibles:** -- El archivo solo tiene símbolos con nombres rechazados por el [Symbol Validity Gate](/guide/symbol-validity-gate) (una sola letra, palabras reservadas, etc.). -- El archivo excede `ghostmap.loading.maxAutoLines` o `ghostmap.loading.maxAutoBytes`. En ese caso el badge del header dirá `[skipped]`. Ver [Loading Policy](/architecture/loading-policy). +**Other possible causes:** +- The file only has symbols with names rejected by the [Symbol Validity Gate](/guide/symbol-validity-gate) (single letters, reserved words, etc.). +- The file exceeds `ghostmap.loading.maxAutoLines` or `ghostmap.loading.maxAutoBytes`. In that case the header badge will say `[skipped]`. See [Loading Policy](/architecture/loading-policy). -## El badge del header se queda en `[loading]` +## The header badge stays on `[loading]` -**Causa más probable:** el language server del lenguaje está frío y bajo presión de RAM, tardando más de 800 ms en responder. GhostMap cae automáticamente al fallback de Tree-sitter + regex, así que el árbol debería aparecer aunque sea con menos detalle. +**Most likely cause:** the language server is cold and under RAM pressure, taking more than 800 ms to respond. GhostMap drops automatically to the Tree-sitter + regex fallback, so the tree should appear even if with less detail. -**Confirmación:** -1. Activa logging: `"ghostmap.performanceLogging": true` en `settings.json`. -2. Reproduce el problema. -3. Abre `Output → GhostMap`. Busca eventos `lsp.timeout` o `refresh.completed`. +**Confirm:** +1. Enable logging: `"ghostmap.performanceLogging": true` in `settings.json`. +2. Reproduce the problem. +3. Open `Output → GhostMap`. Look for `lsp.timeout` or `refresh.completed` events. -**Mitigación inmediata:** cambia de tab al archivo y vuelve. Eso fuerza un refresh nuevo. +**Immediate mitigation:** switch to another tab and back. That forces a fresh refresh. -## El árbol muestra datos "antiguos" +## The tree shows "old" data -El badge dirá `[cached]` o `[stale-cache]`. Significa que GhostMap está pintando desde el snapshot persistente mientras un refresh fresco está en vuelo. En cuestión de segundos el árbol se actualiza. +The badge will say `[cached]` or `[stale-cache]`. It means GhostMap is painting from the persistent snapshot while a fresh refresh is in flight. In a few seconds the tree updates. -Si el badge se queda en `[stale-cache]` indefinidamente, ejecuta `GhostMap: Refresh` desde la paleta de comandos. +If the badge stays on `[stale-cache]` indefinitely, run `GhostMap: Refresh` from the command palette. -## Aparece un anchor pero no en el árbol +## An anchor exists but does not show in the tree -**Causa probable:** el anchor está dentro de un comentario de bloque (`/* @ghost ... */`) o JSDoc (`/** @ghost ... */`). En V1 solo se reconocen anchors dentro de comentarios de línea (`//` o `#`). Ver [Sintaxis](/reference/sintaxis#solo-comentarios-de-línea). +**Likely cause:** the anchor is inside a block comment (`/* @ghost ... */`) or JSDoc (`/** @ghost ... */`). In V1 only anchors inside line comments (`//` or `#`) are recognized. See [Syntax: line comments only](/reference/syntax#line-comments-only). -**Otra causa:** un Range Anchor sin `#nombre`. Es sintácticamente válido pero no genera un nodo. Ver [Range Anchor](/guide/range-anchor#importante-el-nombre-es-obligatorio-para-que-se-vea). +**Another cause:** a Range Anchor without `#name`. It is syntactically valid but does not produce a node. See [Range Anchor](/guide/range-anchor#important-the-name-is-required-for-the-range-to-show). -## "Ranges sin cerrar" o diagnósticos en el editor +## "Unclosed ranges" or diagnostics in the editor -GhostMap detecta varios errores comunes y los reporta como diagnósticos en línea con quick fixes. La lista completa está en [Diagnostics](/reference/diagnostics). +GhostMap detects several common errors and reports them as inline diagnostics with quick fixes. The full list is in [Diagnostics](/reference/diagnostics). -## GhostMap se siente lento al cambiar de tab rápido +## GhostMap feels slow on fast tab switching -El comportamiento es intencional: cuando detecta cambios de tab rápidos (menos de 150 ms entre ellos), GhostMap aplica un backpressure de 200 ms para evitar encolar análisis innecesarios. Archivos pequeños (≤ 50 líneas) saltan este retraso automáticamente. +The behavior is intentional: when it detects fast tab switches (less than 150 ms between them), GhostMap applies a 200 ms backpressure to avoid queueing unnecessary analyses. Small files (50 lines or fewer) skip this delay automatically. -Si te molesta en archivos medianos, sube `ghostmap.loading.tinyLineThreshold` a 200 o más. +If it bothers you on medium files, raise `ghostmap.loading.tinyLineThreshold` to 200 or more. -## El panel no aparece después de instalar +## The panel does not appear after install -1. Abre cualquier archivo en un lenguaje soportado. -2. Mira la barra lateral izquierda: debería haber un icono nuevo de fantasma. -3. Si no aparece, reinicia VS Code (`Developer: Reload Window` desde la paleta). -4. Verifica que la extensión esté activa: ve a `Extensions` y busca "GhostMap". +1. Open any file in a supported language. +2. Look at the left side bar: there should be a new ghost icon. +3. If it does not appear, restart VS Code (`Developer: Reload Window` from the palette). +4. Check that the extension is active: go to `Extensions` and search "GhostMap". -## Reportar un bug +## Report a bug -Si los pasos anteriores no resuelven tu problema, escribí a [getghostmap@proton.me](mailto:getghostmap@proton.me) con la siguiente información: +If the steps above do not solve your problem, write to [getghostmap@proton.me](mailto:getghostmap@proton.me) with the following: -- Versión de VS Code (`Help → About`) -- Versión de GhostMap (panel de Extensions) -- Sistema operativo -- Language ID del archivo afectado -- Cantidad de líneas -- Qué dice el badge del header -- Lo que esperabas vs. lo que pasó -- Pasos para reproducir -- Si es posible, salida del Output → GhostMap con `performanceLogging` activado +- VS Code version (`Help → About`) +- GhostMap version (Extensions panel) +- Operating system +- Language ID of the affected file +- Line count +- What the header badge shows +- What you expected vs. what happened +- Steps to reproduce +- If possible, the `Output → GhostMap` log with `performanceLogging` enabled -## Siguiente paso +## Next step -Si tienes una pregunta general en lugar de un bug, revisa el **[FAQ](/faq)**. +If you have a general question instead of a bug, check the **[FAQ](/faq)**. diff --git a/docs/uninstall.md b/docs/uninstall.md index 938e388..0ce09dd 100644 --- a/docs/uninstall.md +++ b/docs/uninstall.md @@ -1,51 +1,51 @@ --- id: uninstall -title: Cómo desinstalar -sidebar_label: Desinstalar +title: How to uninstall +sidebar_label: Uninstall --- -# Cómo desinstalar GhostMap +# How to uninstall GhostMap -Tres pasos: quitar la extensión, opcionalmente limpiar los settings, opcionalmente borrar el caché de workspaces. +Three steps: remove the extension, optionally clean the settings, optionally delete the workspace caches. -## 1. Quitar la extensión +## 1. Remove the extension -Desde VS Code: +From VS Code: -1. Abre el panel **Extensions** (`Ctrl+Shift+X` / `Cmd+Shift+X`). -2. Busca **GhostMap**. -3. Click en el engranaje, **Uninstall**. +1. Open the **Extensions** panel (`Ctrl+Shift+X` / `Cmd+Shift+X`). +2. Search **GhostMap**. +3. Click the gear icon, **Uninstall**. -Desde la línea de comandos: +From the command line: ```bash code --uninstall-extension ghostmap.ghostmap ``` -VS Code te pedirá recargar la ventana. Después de eso, el panel y los comandos `GhostMap: *` desaparecen. +VS Code will ask you to reload the window. After that the panel and the `GhostMap: *` commands disappear. -## 2. (Opcional) Quitar los settings +## 2. (Optional) Remove the settings -VS Code conserva los settings de extensiones desinstaladas en caso de que reinstales. Si quieres limpiarlos: +VS Code keeps settings for uninstalled extensions in case you reinstall. If you want to clean them: -1. Abre `settings.json` (User o Workspace). -2. Borra cualquier clave que empiece con `"ghostmap."`. +1. Open `settings.json` (User or Workspace). +2. Delete any key that starts with `"ghostmap."`. -No hay efecto colateral; si reinstalas más tarde, GhostMap usará los valores por defecto. +There is no side effect; if you reinstall later, GhostMap uses the defaults. -## 3. (Opcional) Borrar los caches `.ghostmap/` +## 3. (Optional) Delete the `.ghostmap/` caches -GhostMap deja un archivo `.ghostmap/ghostmap.json` por workspace que tocaste. Si quieres limpiar todos: +GhostMap leaves a `.ghostmap/ghostmap.json` file per workspace you touched. If you want to wipe them all: **Cross-platform (Node):** ```bash -# Encuentra y elimina .ghostmap/ recursivamente desde un directorio raíz que contenga tus proyectos. -# Cuidado con el alcance: este comando borra TODOS los .ghostmap que encuentre desde donde lo lances. +# Find and remove .ghostmap/ recursively from a root directory that contains your projects. +# Mind the scope: this command removes EVERY .ghostmap it finds from where you launch it. node -e "const fs=require('fs'),p=require('path');function walk(d){for(const f of fs.readdirSync(d,{withFileTypes:true})){const x=p.join(d,f.name);if(f.isDirectory()){if(f.name==='.ghostmap'){fs.rmSync(x,{recursive:true,force:true});console.log('deleted',x);}else if(f.name!=='node_modules'&&f.name!=='.git'){walk(x);}}}};walk(process.cwd());" ``` -O simplemente en cada workspace, manualmente: +Or simply, in each workspace, manually: ```bash rm -rf .ghostmap/ @@ -55,15 +55,15 @@ rm -rf .ghostmap/ Remove-Item -Recurse -Force .ghostmap\ ``` -## Lo que NO hace falta tocar +## What you do NOT need to touch -- Las **gramáticas Tree-sitter** ya viven dentro de la carpeta de la extensión (`~/.vscode/extensions/ghostmap.ghostmap-/`). Al desinstalar el extension, VS Code limpia esa carpeta automáticamente. -- No hay variables de entorno, demonios, ni servicios en background. GhostMap solo vive como Extension Host process. +- The **Tree-sitter grammars** already live inside the extension folder (`~/.vscode/extensions/ghostmap.ghostmap-/`). When you uninstall the extension, VS Code cleans that folder automatically. +- There are no environment variables, daemons, or background services. GhostMap only lives as an Extension Host process. -## Reinstalar +## Reinstall -Si decides volver, los pasos son los mismos que la primera vez: ver [Instalación](/get-started/instalacion). Tu `.gitignore` y tus settings (si no los borraste) siguen donde estaban. +If you decide to come back, the steps are the same as the first time: see [Install](/install). Your `.gitignore` and your settings (if you did not delete them) stay where they were. -## ¿Por qué me iría? +## Why would I leave? -Si encontraste un problema, considera mandar un mail a [getghostmap@proton.me](mailto:getghostmap@proton.me) antes de irte. El proyecto está en desarrollo activo y los reports concretos son lo que hace que los gaps se cierren. +If you hit a problem, consider sending a mail to [getghostmap@proton.me](mailto:getghostmap@proton.me) before going. The project is in active development and concrete reports are what close the gaps. diff --git a/docs/vsix-install.md b/docs/vsix-install.md index 3932e28..500fbb7 100644 --- a/docs/vsix-install.md +++ b/docs/vsix-install.md @@ -1,32 +1,32 @@ --- id: vsix-install -title: Instalar desde un archivo VSIX -sidebar_label: Instalar desde VSIX +title: Install from a VSIX file +sidebar_label: Install from VSIX --- -# Instalar GhostMap desde un archivo VSIX +# Install GhostMap from a VSIX file -Hoy el VSIX entregado por contacto directo es el **camino único** de instalación de GhostMap, no solo un fallback. El paquete todavía no está publicado en VS Code Marketplace (falta dar de alta al `publisher`) y Open VSX tiene el script de publicación (`publish:open-vsx`, que invoca `ovsx publish`) ya preparado en `package.json`, pero quedan pendientes el namespace en open-vsx.org, el token y el primer publish. GitHub Releases queda como canal planificado post-tag; todavía no hay release público y el repositorio fuente sigue privado. Mientras tanto, todos los usuarios — incluso quienes están en VS Code estándar — instalan vía VSIX recibido por mail. +Today the VSIX delivered by direct contact is the **only** install path for GhostMap, not just a fallback. The package is not yet on the VS Code Marketplace (publisher onboarding is pending) and Open VSX has the publish script (`publish:open-vsx`, calling `ovsx publish`) prepared in `package.json`, but the namespace on open-vsx.org, the token, and the first publish are still pending. GitHub Releases is the planned post-tag channel; there is no public release yet and the source repository is still private. In the meantime, every user (including users on standard VS Code) installs via VSIX received by email. -Ver el estado de cada canal en **[Instalación → Estado de distribución](/get-started/instalacion)**. +See the per-channel state in **[Install](/install)**. -Este archivo también te sirve si más adelante necesitas: +This file is also useful when you later need: -- Instalación **offline** o en una máquina sin acceso a la red. -- **Pinning** a una versión concreta para reproducibilidad. -- Entornos corporativos donde Marketplace/Open VSX están bloqueados. +- **Offline** install or a machine without network access. +- **Pinning** to a specific version for reproducibility. +- Corporate setups where Marketplace and Open VSX are blocked. -## Obtener el VSIX +## Get the VSIX -### Opción A (recomendada hoy): pedir el VSIX por mail +### Option A (recommended today): request the VSIX by email -Escribí a [getghostmap@proton.me](mailto:getghostmap@proton.me) indicando que querés el paquete de instalación. Te respondemos con el archivo `ghostmap-0.5.0.vsix` listo para instalar. +Write to [getghostmap@proton.me](mailto:getghostmap@proton.me) saying you want the install package. You will receive the `ghostmap-0.5.0.vsix` file ready to install. -Este es el camino oficial mientras Marketplace, Open VSX y el repositorio público estén pendientes. +This is the official path while Marketplace, Open VSX, and the public repository are pending. -### Opción B: empaquetar desde el código fuente (solo con acceso al repo) +### Option B: build the VSIX from source (requires repo access) -El repositorio `genesis` es privado y el acceso es limitado. Si te otorgaron acceso explícito, podés empaquetarlo vos mismo: +The `genesis` repository is private and access is limited. If you have explicit access, you can package it yourself: ```bash cd genesis @@ -35,52 +35,52 @@ npm run compile npx @vscode/vsce package --out ghostmap.vsix ``` -El archivo `ghostmap.vsix` queda en el directorio actual. Si no tenés acceso al repo, usá la Opción A. +The `ghostmap.vsix` file lands in the current directory. If you do not have repo access, use Option A. -### Opción C: descargar un VSIX publicado cuando exista +### Option C: download a published VSIX when one exists -Cuando exista un release público, el VSIX se anunciará por los canales de distribución oficiales (este documento se actualizará con la URL exacta). Hasta entonces, usá la Opción A. +When a public release exists, the VSIX will be announced through the official distribution channels (this document will be updated with the exact URL). Until then, use Option A. -## Instalar el VSIX +## Install the VSIX -### Desde VS Code (UI) +### From VS Code (UI) -1. Abre el panel **Extensions** (`Ctrl+Shift+X` / `Cmd+Shift+X`). -2. Click en el menú "..." de la barra superior del panel. +1. Open the **Extensions** panel (`Ctrl+Shift+X` / `Cmd+Shift+X`). +2. Click the "..." menu on the top bar of the panel. 3. **Install from VSIX...** -4. Selecciona el archivo `ghostmap.vsix`. -5. VS Code instala y te pide recargar. +4. Pick the `ghostmap.vsix` file. +5. VS Code installs and asks you to reload. -### Desde la línea de comandos +### From the command line ```bash code --install-extension ghostmap.vsix ``` -## Verificar la instalación +## Verify the install -Después de recargar VS Code: +After reloading VS Code: -1. Abre cualquier archivo de un lenguaje soportado (por ejemplo `.ts`). -2. En la barra lateral izquierda debería aparecer un icono nuevo de fantasma. -3. Click en el icono: el panel **GhostMap** muestra el árbol de símbolos del archivo activo. +1. Open any file of a supported language (for example `.ts`). +2. A new ghost icon should appear in the left side bar. +3. Click the icon: the **GhostMap** panel shows the symbol tree of the active file. -Si el panel está vacío y el archivo tiene símbolos, abre la paleta y ejecuta `GhostMap: Refresh`; si sigue vacío, escríbenos a getghostmap@proton.me con la versión de VS Code y el lenguaje del archivo. +If the panel is empty and the file has symbols, open the palette and run `GhostMap: Refresh`; if it is still empty, write to getghostmap@proton.me with the VS Code version and the file's language. -## Actualizar a una versión nueva +## Update to a new version -Repite el proceso con el nuevo VSIX. VS Code detecta que es una nueva versión del mismo extension y la actualiza in-place. No hace falta desinstalar primero. +Repeat the process with the new VSIX. VS Code detects it as a new version of the same extension and updates it in place. There is no need to uninstall first. -## Restricciones del modo VSIX +## VSIX mode restrictions -Cuando instalas desde VSIX (que hoy es el modo por defecto): +When you install from VSIX (which is the default mode today): -- VS Code **no** te avisa automáticamente cuando hay una versión nueva. Tienes que comprobar manualmente el repo o, cuando existan releases públicos, la página de GitHub Releases. -- El extension se marca como "side-loaded" y no aparece en tus extensiones sincronizadas si usas Settings Sync. -- En entornos gestionados por IT, puede que la política bloquee instalaciones VSIX. Consulta con tu administrador. +- VS Code does **not** notify you automatically when a new version exists. You have to check manually, or, when public releases exist, the GitHub Releases page. +- The extension is marked as "side-loaded" and does not appear in your synced extensions if you use Settings Sync. +- In IT-managed environments, policy may block VSIX installs. Check with your administrator. -Cuando se publique GhostMap en VS Code Marketplace y Open VSX (ambos están pendientes/planificados — ver [Estado del proyecto](/status/estado-del-proyecto)), los avisos de actualización in-editor y la sincronización de Settings Sync funcionarán de forma estándar. +When GhostMap is published on VS Code Marketplace and Open VSX (both pending/planned: see [Project status](/status/project-status)), in-editor update notifications and Settings Sync will work in the standard way. -## Siguiente paso +## Next step -Continúa con **[Primeros 5 minutos](/get-started/primeros-5-minutos)** para escribir tu primer anchor `@ghost`. +Continue with **[First 5 minutes](/get-started/first-5-minutes)** to write your first `@ghost` anchor. diff --git a/docusaurus.config.js b/docusaurus.config.js index 935c8a8..f131012 100644 --- a/docusaurus.config.js +++ b/docusaurus.config.js @@ -4,8 +4,8 @@ import {themes as prismThemes} from 'prism-react-renderer'; /** @type {import('@docusaurus/types').Config} */ const config = { title: 'GhostMap', - tagline: 'Estructura de proyecto, dentro de tu código.', - favicon: 'img/favicon.svg', + tagline: 'Project structure, inside your code.', + favicon: 'img/favicon.png', future: { v4: true, @@ -30,11 +30,6 @@ const config = { }, }, - i18n: { - defaultLocale: 'es', - locales: ['es'], - }, - headTags: [ { tagName: 'meta', @@ -87,7 +82,7 @@ const config = { themeConfig: /** @type {import('@docusaurus/preset-classic').ThemeConfig} */ ({ - image: 'img/ghost-logo.svg', + image: 'img/ghost-logo.png', colorMode: { defaultMode: 'dark', respectPrefersColorScheme: false, @@ -95,7 +90,7 @@ const config = { announcementBar: { id: 'v1-prerelease', content: - 'GhostMap V1 está en pre-release. La sintaxis @ghost y los settings son estables, pero pueden ajustarse en versiones futuras antes de la 1.0.', + 'GhostMap V1 is in pre-release. @ghost syntax and settings are stable, but may still change before 1.0.', backgroundColor: '#0e0e1a', textColor: '#eeeef5', isCloseable: true, @@ -104,23 +99,32 @@ const config = { title: 'GhostMap', logo: { alt: 'GhostMap logo', - src: 'img/ghost-logo.svg', + src: 'img/ghost-logo.png', }, items: [ { - type: 'docSidebar', - sidebarId: 'docsSidebar', + to: '/', + label: 'Start', + position: 'left', + }, + { + to: '/overview', + label: 'Overview', + position: 'left', + }, + { + to: '/changelog', + label: 'Changelog', position: 'left', - label: 'Docs', }, { href: 'mailto:getghostmap@proton.me', - label: 'Contacto', + label: 'Contact', position: 'right', }, { - to: '/get-started/instalacion', - label: 'Instalar (VSIX local)', + to: '/install', + label: 'Install', position: 'right', className: 'navbar-cta', }, @@ -130,38 +134,30 @@ const config = { style: 'dark', links: [ { - title: 'Producto', - items: [ - {label: 'Inicio', to: '/'}, - {label: 'Roadmap', to: '/roadmap/vision-v2'}, - {label: 'Estado del proyecto', to: '/status/estado-del-proyecto'}, - ], - }, - { - title: 'Documentación', + title: 'Product', items: [ - {label: 'Guía rápida', to: '/get-started/instalacion'}, - {label: 'Conceptos', to: '/guide/symbol'}, - {label: 'Referencia', to: '/reference/sintaxis'}, - {label: 'FAQ', to: '/faq'}, + {label: 'Start', to: '/'}, + {label: 'Overview', to: '/overview'}, + {label: 'Install', to: '/install'}, + {label: 'Changelog', to: '/changelog'}, ], }, { title: 'Legal', items: [ + {label: 'Legal & Support', to: '/legal-support'}, {label: 'Privacy Policy', to: '/legal/privacy'}, {label: 'Terms of Use', to: '/legal/terms'}, {label: 'Third-Party Notices', to: '/legal/notices'}, {label: 'Disclaimer', to: '/legal/disclaimer'}, - {label: 'Consultas legales (email)', href: 'mailto:getghostmap@proton.me'}, ], }, { - title: 'Comunidad', + title: 'Community', items: [ {label: 'Support GhostMap', href: 'https://ghostmap-liard.vercel.app/#support'}, {label: 'getghostmap@proton.me', href: 'mailto:getghostmap@proton.me'}, - {label: 'Reportar un bug', href: 'mailto:getghostmap@proton.me'}, + {label: 'Report a bug', href: 'mailto:getghostmap@proton.me'}, ], }, ], diff --git a/sidebars.js b/sidebars.js index 6b51389..4007824 100644 --- a/sidebars.js +++ b/sidebars.js @@ -3,26 +3,21 @@ /** @type {import('@docusaurus/plugin-content-docs').SidebarsConfig} */ const sidebars = { docsSidebar: [ - { - type: 'doc', - id: 'intro', - label: 'Introducción', - }, + 'intro', + 'overview', { type: 'category', - label: 'Empezar', - collapsed: false, + label: 'Get started', items: [ - 'get-started/requisitos', - 'get-started/instalacion', + 'install', 'vsix-install', - 'get-started/primeros-5-minutos', + 'get-started/requirements', + 'get-started/first-5-minutes', ], }, { type: 'category', - label: 'Guía / Conceptos', - collapsed: false, + label: 'Guide', items: [ 'guide/philosophy', 'guide/symbol', @@ -39,56 +34,40 @@ const sidebars = { }, { type: 'category', - label: 'Referencia', - collapsed: false, + label: 'Reference', items: [ - 'reference/sintaxis', + 'reference/syntax', 'reference/ghost-tree', 'reference/diagnostics', 'reference/settings', - 'reference/rendimiento', + 'reference/performance', 'keyboard-shortcuts', ], }, { type: 'category', - label: 'Arquitectura', + label: 'Architecture', items: [ - 'architecture/arquitectura-v1', + 'architecture/v1', 'architecture/loading-policy', 'architecture/local-state', - 'data-location', ], }, { type: 'category', - label: 'Ayuda', + label: 'Project', items: [ - 'faq', + 'status/project-status', + 'roadmap/v2', + 'data-location', 'troubleshooting', + 'faq', 'glossary', 'uninstall', ], }, - { - type: 'doc', - id: 'changelog', - label: 'Changelog', - }, - { - type: 'category', - label: 'Roadmap', - items: [ - 'roadmap/vision-v2', - ], - }, - { - type: 'category', - label: 'Estado', - items: [ - 'status/estado-del-proyecto', - ], - }, + 'legal-support', + 'changelog', { type: 'category', label: 'Legal', diff --git a/src/css/custom.css b/src/css/custom.css index 6f4c9ea..b7fab09 100644 --- a/src/css/custom.css +++ b/src/css/custom.css @@ -1,5 +1,5 @@ /** - * GhostMap Docs — theme tokens + * GhostMap Docs theme tokens * Paleta tomada del landing: fondo casi negro, acentos violeta/morado. */ diff --git a/static/img/favicon.ico b/static/img/favicon.ico deleted file mode 100644 index c01d54b..0000000 Binary files a/static/img/favicon.ico and /dev/null differ diff --git a/static/img/favicon.png b/static/img/favicon.png new file mode 100644 index 0000000..2023996 Binary files /dev/null and b/static/img/favicon.png differ diff --git a/static/img/favicon.svg b/static/img/favicon.svg deleted file mode 100644 index 5543fad..0000000 --- a/static/img/favicon.svg +++ /dev/null @@ -1,11 +0,0 @@ - - - - - - - - - - - diff --git a/static/img/ghost-logo.png b/static/img/ghost-logo.png new file mode 100644 index 0000000..b440f25 Binary files /dev/null and b/static/img/ghost-logo.png differ diff --git a/static/img/ghost-logo.svg b/static/img/ghost-logo.svg deleted file mode 100644 index 5543fad..0000000 --- a/static/img/ghost-logo.svg +++ /dev/null @@ -1,11 +0,0 @@ - - - - - - - - - - - diff --git a/static/img/logo.svg b/static/img/logo.svg deleted file mode 100644 index 9db6d0d..0000000 --- a/static/img/logo.svg +++ /dev/null @@ -1 +0,0 @@ - \ No newline at end of file diff --git a/vercel.json b/vercel.json new file mode 100644 index 0000000..9fb7ba5 --- /dev/null +++ b/vercel.json @@ -0,0 +1,8 @@ +{ + "$schema": "https://openapi.vercel.sh/vercel.json", + "framework": "docusaurus-2", + "buildCommand": "npm run build", + "outputDirectory": "build", + "cleanUrls": true, + "trailingSlash": false +}