diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 00000000..945d5ce6 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,73 @@ +# Repository Guidelines + +## Quick Links + +- `package.json` (commands, settings, contributes) +- `src/extension.ts` (activation + registration hub) +- `src/ccs/index.ts` (Consistem fork entrypoints) + +## Project Structure & Module Organization + +- `src/`: TypeScript source for the VS Code extension. + - `src/commands/`, `src/providers/`, `src/explorer/`, `src/api/`, `src/utils/`: feature modules. + - `src/test/`: extension integration test harness. +- `src/ccs/`: **Consistem fork layer** (custom commands/providers/integrations kept isolated to reduce upstream merge conflicts). +- `syntaxes/` and `language-configuration*.json*`: language grammar + editor configuration for ObjectScript. +- `snippets/`: VS Code snippet definitions. +- `webview/`: webview assets used by the extension UI. +- `images/`: icons and documentation images. +- `test-fixtures/`: workspace fixtures used by integration tests. + +## Consistem Fork Notes (Merge-Safe Customizations) + +- Prefer implementing Consistem-only behavior inside `src/ccs/` and wiring it up from `src/extension.ts` (command registration, providers, settings). +- This fork talks to **two** server surfaces: + - Official upstream integration via Atelier (`/api/atelier/...`) for standard features. + - Consistem internal SourceControl API under `src/ccs/sourcecontrol/` (default base path: `/api/sourcecontrol/vscode`), derived from the active Atelier connection and optionally overridden via `objectscript.ccs.endpoint`. +- If you must change upstream-owned modules, keep the diff small and route Consistem logic through `src/ccs/` to make future upstream updates easier. + +## Hierarchical Agent Instructions + +This repo uses “Hierarchical Agent Instructions”: folders may contain their own `AGENTS.md` with **more specific** rules. + +- When working on files under a directory, follow the closest `AGENTS.md` in that directory tree. +- This repository keeps a minimal, common structure: + - Root `AGENTS.md` (general rules and contributor guide) + - `src/AGENTS.md` (TypeScript/VS Code extension conventions) + - `src/ccs/AGENTS.md` (Consistem fork layer conventions) + +## Build, Test, and Development Commands + +- `npm install`: installs dependencies (also runs `postinstall` to sync VS Code API typings). +- `npm run compile`: production build (`webpack` + `tsc`). +- `npm run webpack-dev`: development bundle in watch mode. +- `npm run watch`: TypeScript watch build (useful for typechecking). +- `npm test`: runs integration tests via `@vscode/test-electron` (downloads VS Code and installs dependent extensions). +- `npm run lint` / `npm run lint-fix`: runs ESLint on `src/**`. +- `npm run package`: produces a `.vsix` via `vsce package`. + +For interactive debugging, use VS Code’s `Run and Debug` launch config (see `.vscode/launch.json`) to start an “Extension Development Host”. + +## Dependency Changes + +- Prefer reusing existing dependencies; adding new runtime deps increases extension size and supply-chain surface area. +- When you do add/remove deps, keep `package.json` and `package-lock.json` in sync and ensure `npm run compile` stays clean. + +## Coding Style & Naming Conventions + +- Indentation: 2 spaces (see `.editorconfig`). +- Formatting: Prettier settings in `.prettierrc` (e.g., `printWidth: 120`). +- Linting: ESLint flat config in `eslint.config.mjs`; keep changes lint-clean. +- Prefer descriptive names; keep VS Code command IDs under the existing `vscode-objectscript.*` namespace. + +## Testing Guidelines + +- Framework: Mocha (TDD UI) running inside a VS Code test instance. +- Location/pattern: add tests in `src/test/suite/` using `*.test.ts` naming. +- Keep tests hermetic: rely on `test-fixtures/` instead of a real server when possible. + +## Commit & Pull Request Guidelines + +- Commit messages typically use an imperative subject and often include a PR reference, e.g. `Fix unit test failure (#73)`. +- Work on a branch (not `master`). PRs should include: problem statement, approach, testing notes, and screenshots for UI/webview changes. +- Keep CI green; governance requires PMC review/approvals (see `GOVERNANCE.md` and `CONTRIBUTING.md`). If a change is user-facing, update `CHANGELOG.md`. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 7b1e9d62..7943eb81 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,67 +1,73 @@ -# Contributing to the ObjectScript extension for Visual Studio Code +# Contribuindo para o `vscode-objectscript` (fork Consistem) -## Contributing a pull request +Este repositório é um fork do `intersystems-community/vscode-objectscript`. As customizações da Consistem devem, sempre que possível, ficar isoladas em `src/ccs/` para reduzir conflitos quando atualizarmos o upstream. -### Prerequisites +## Pré-requisitos 1. [Node.js](https://nodejs.org/) 18.x -1. Windows, macOS, or Linux -1. [Visual Studio Code](https://code.visualstudio.com/) -1. The following VS Code extensions: - - [ESLint](https://marketplace.visualstudio.com/items?itemName=dbaeumer.vscode-eslint) - - [Prettier](https://marketplace.visualstudio.com/items?itemName=esbenp.prettier-vscode) - - [EditorConfig for VS Code](https://marketplace.visualstudio.com/items?itemName=EditorConfig.EditorConfig) +2. Windows, macOS ou Linux +3. [Visual Studio Code](https://code.visualstudio.com/) +4. Extensões do VS Code: + - [ESLint](https://marketplace.visualstudio.com/items?itemName=dbaeumer.vscode-eslint) + - [Prettier](https://marketplace.visualstudio.com/items?itemName=esbenp.prettier-vscode) + - [EditorConfig for VS Code](https://marketplace.visualstudio.com/items?itemName=EditorConfig.EditorConfig) -### Setup +## Setup -```shell -git clone https://github.com/intersystems-community/vscode-objectscript +```sh +git clone https://github.com/consistem/vscode-objectscript cd vscode-objectscript npm install ``` -### Errors and Warnings +## Fluxo de Desenvolvimento -TypeScript errors and warnings will be displayed in the `PROBLEMS` panel of Visual Studio Code. +- Abra a pasta do projeto no VS Code. +- Use `Run and Debug` → `Launch Extension` (ou `Launch Extension Alone`) para abrir um `[Extension Development Host]` e validar as mudanças. +- Erros/avisos TypeScript aparecem no painel `PROBLEMS`. -### Editing code snippets +Comandos úteis: -Code snippets are defined in files in the /snippets/ folder: - -* objectscript-class.json - snippets for class definition context -* objectscript.json - snippets for objectscript context -* objectscript.json - snippets for consistem objectscript context - -Snippets syntax is described [here](https://code.visualstudio.com/docs/editor/userdefinedsnippets). - -### Run dev build and validate your changes +```sh +npm run compile # build de produção (webpack + tsc) +npm run webpack-dev # build em watch (webpack) +npm run watch # typecheck em watch (tsc) +npm run lint # ESLint em src/** +npm test # testes de integração (VS Code + Mocha) +``` -To test changes, open the `vscode-objectscript` folder in VSCode. -Then, open the debug panel by clicking the `Run and Debug` icon on the Activity Bar, select the `Launch Extension` -option from the top menu, and click start. A new window will launch with the title -`[Extension Development Host]`. Do your testing here. +## Snippets -If you want to disable all other extensions when testing in the Extension Development Host, choose the `Launch Extension Alone` option instead. +Os snippets ficam em `snippets/`: -### Pull requests +- `snippets/objectscript-class.json`: contexto de definição de classes +- `snippets/objectscript.json`: ObjectScript (geral) +- `snippets/consistem-objectscript.json`: snippets específicos do fork Consistem -Work should be done on a unique branch -- not the master branch. Pull requests require the approval of two PMC members, as described in the [Governance document](GOVERNANCE.md). PMC review is often high level, so in addition to that, you should request a review by someone familiar with the technical details of your particular pull request. +Referência de sintaxe: https://code.visualstudio.com/docs/editor/userdefinedsnippets -We do expect CI to be passing for a pull request before we will consider merging it. CI executed by pull requests will produce a `vsix` file, which can be downloaded and installed manually to test proposed functionality. +## Customizações Consistem (src/ccs) -## Beta versions +- Implementações específicas devem morar em `src/ccs/` (comandos, providers e integrações internas). +- Conexões internas são derivadas da conexão ativa do Atelier, com override opcional por `objectscript.ccs.endpoint`. +- Quando uma feature “substitui” comportamento padrão (ex.: F12/Ctrl+Click), mantenha fallback para o comportamento nativo do VS Code quando a resolução interna falhar. -Any change to `master` branch will call CI, which will produce [beta release](https://github.com/intersystems-community/vscode-objectscript/releases), which can be manually installed. +## Branches, Commits e Pull Requests -## Local Build +- Trabalhe em uma branch (não faça commit direto em `master`). +- Branches principais: + - `master`: linha principal (CI e releases). + - `prerelease`: linha de pré-release (quando aplicável). +- Commits: siga o padrão do histórico do repositório (assunto imperativo; muitas vezes com referência `(#NN)`). +- PRs devem incluir: descrição objetiva, motivação, como testar (passos), e screenshots para alterações visuais (webview/UI). +- O CI precisa estar verde; PRs geram artefatos `.vsix` nos workflows do GitHub Actions para teste manual. -Steps to build the extension on your machine once you've cloned the repo: +## Build Local (VSIX) -```bash -> npm install -g vsce -# Perform the next steps in the vscode-objectscript folder. -> npm install -> npm run package +```sh +npm install -g vsce +npm install +npm run package ``` -Resulting in a `vscode-objectscript-$VERSION.vsix` file in your `vscode-objectscript` folder. +Isso gera um arquivo `vscode-objectscript-$VERSION.vsix` na raiz do projeto. diff --git a/README.md b/README.md index 94a6dacf..7ea3882d 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,13 @@ +

+ Consistem +

+ +> **Fork Consistem:** esta extensão é um fork do projeto oficial [`intersystems-community/vscode-objectscript`](https://github.com/intersystems-community/vscode-objectscript). +> +> Ele preserva todas as funcionalidades do projeto original e adiciona integrações, ajustes e padrões internos adotados pela Consistem, com foco em atender necessidades específicas do nosso ecossistema de desenvolvimento. + +--- + [![Known Vulnerabilities](https://snyk.io/test/github/intersystems-community/vscode-objectscript/badge.svg)](https://snyk.io/test/github/intersystems-community/vscode-objectscript) ![Visual Studio Marketplace Version](https://img.shields.io/visual-studio-marketplace/v/intersystems-community.vscode-objectscript.svg) [![](https://img.shields.io/visual-studio-marketplace/i/intersystems-community.vscode-objectscript.svg)](https://marketplace.visualstudio.com/items?itemName=intersystems-community.vscode-objectscript) diff --git a/images/logo-consistem-horizontal.png b/images/logo-consistem-horizontal.png new file mode 100644 index 00000000..29b42c8b Binary files /dev/null and b/images/logo-consistem-horizontal.png differ diff --git a/src/AGENTS.md b/src/AGENTS.md new file mode 100644 index 00000000..4a9d01e1 --- /dev/null +++ b/src/AGENTS.md @@ -0,0 +1,44 @@ +# Agent Instructions (src/) + +Scope: everything under `src/`. + +## Quick Links + +- `src/extension.ts` (activation + registration hub) +- `src/utils/index.ts` (shared utilities + `handleError()`) +- `src/test/suite/` (integration tests) + +## Architecture & Boundaries + +- `src/extension.ts` is the main activation/registration hub. New commands/providers should be registered here. +- Treat `src/ccs/` as the **Consistem customization layer**. Prefer adding new Consistem rules, APIs, and UX there to keep upstream merges clean. +- Avoid coupling Consistem features deeply into upstream modules; keep adapters thin and move behavior into `src/ccs/`. + +## Commands, IDs, and Configuration + +- Keep command IDs in the existing namespace: + - Upstream: `vscode-objectscript.*` + - Consistem: `vscode-objectscript.ccs.*` (category “Consistem” in `package.json`). +- When you add a new command: + 1) add it to `package.json` under `contributes.commands` (and keybindings/menus if needed), + 2) register it in `src/extension.ts`, + 3) add telemetry event wiring if the surrounding pattern does. +- When you add/update settings: + - define them in `package.json` under `contributes.configuration`, + - keep Consistem-specific keys under `objectscript.ccs.*` (see `src/ccs/AGENTS.md`). + +## Error Handling & Logging + +- Prefer `handleError()` for user-facing error surfacing. +- Avoid `console.*` for runtime logging; follow the established Output channel / logging utilities patterns. +- Don’t leak credentials or full URLs with embedded auth in logs. + +## Style + +- 2-space indentation (see `.editorconfig`), Prettier + ESLint enforced. +- Match existing patterns (async/await, early returns, explicit typing where it adds clarity). + +## Performance & UX + +- Providers run frequently; avoid doing network calls per keystroke. +- Prefer progress notifications (`withProgress`) for operations that may take noticeable time. diff --git a/src/ccs/AGENTS.md b/src/ccs/AGENTS.md new file mode 100644 index 00000000..2f5f6bfa --- /dev/null +++ b/src/ccs/AGENTS.md @@ -0,0 +1,72 @@ +# Agent Instructions (src/ccs/) + +Scope: everything under `src/ccs/` (Consistem fork layer). + +## Quick Links + +- `src/ccs/config/settings.ts` (`objectscript.ccs.*` settings contract) +- `src/ccs/core/http.ts` (HTTP client factory) +- `src/ccs/sourcecontrol/routes.ts` (internal API route table) + +## Purpose (Keep Merges Easy) + +- This directory exists to isolate Consistem-specific behavior from upstream code. +- Prefer implementing new Consistem rules/features here and exposing them via `src/ccs/index.ts`, with minimal wiring in `src/extension.ts`. + +## Ownership & Wiring + +- Expose public entrypoints from `src/ccs/index.ts` and keep call sites in `src/extension.ts` small. +- Commands in this layer use the `vscode-objectscript.ccs.*` namespace and are typically shown under the “Consistem” category in `package.json`. +- If a CCS feature replaces upstream behavior (ex.: F12 / go to definition), always provide a safe fallback to the default VS Code command when CCS resolution fails. + +## Settings Contract (objectscript.ccs.*) + +- Settings are read on-demand via `getCcsSettings()` (`src/ccs/config/settings.ts`). +- Keys live under `objectscript.ccs.*` (ex.: `endpoint`, `requestTimeout`, `debugLogging`, `flags`). +- Treat these as a stable contract for Consistem users: avoid breaking changes; sanitize inputs in `settings.ts` (not scattered across features). + +## Server Integrations (Internal APIs) + +- CCS calls are routed through `SourceControlApi` (`src/ccs/sourcecontrol/client.ts`) and the route table in `src/ccs/sourcecontrol/routes.ts`. +- Default base URL is derived from the active Atelier connection; it can be overridden via `objectscript.ccs.endpoint` (see `src/ccs/config/settings.ts`). +- Keep new endpoints behind a small `clients/*Client.ts` wrapper and typed response shapes in `src/ccs/core/types.ts`. +- Treat `src/ccs/sourcecontrol/routes.ts` as the source of truth; if you update routes, update this doc (or remove stale endpoint notes). + +### Current Internal Endpoints (as of this fork) + +Base path: `GET/POST {baseURL}/api/sourcecontrol/vscode` (see `BASE_PATH` in `src/ccs/sourcecontrol/routes.ts`). + +- `POST /resolveContextExpression` + - Used by: `vscode-objectscript.ccs.resolveContextExpression` (`src/ccs/commands/contextHelp.ts`) + - Behavior: sends routine + selected/line expression; may return preview content and a `textExpression` to insert. +- `POST /getGlobalDocumentation` + - Used by: `vscode-objectscript.ccs.getGlobalDocumentation` (`src/ccs/commands/globalDocumentation.ts`) + - Behavior: fetches “global documentation” text for the selection/query. +- `POST /namespaces/{NAMESPACE}/resolveDefinition` + - Used by: F12 / Ctrl+Click path via CCS definition lookup (`src/ccs/features/definitionLookup/*` + `src/ccs/commands/goToDefinitionLocalFirst.ts`) + - Behavior: resolves symbols using Consistem’s internal server logic; should fall back to VS Code default when it can’t resolve. +- `POST /namespaces/{NAMESPACE}/createItem` + - Used by: `vscode-objectscript.ccs.createItem` (`src/ccs/commands/createItem.ts`) + - Behavior: creates a class/routine on the server and returns a file path to open locally. +- `POST /namespaces/{NAMESPACE}/unitTests/runUnitTests` + - Used by: unit test runner integration (`src/commands/unitTest.ts` via `src/ccs/sourcecontrol/routes.ts`) + - Behavior: runs server-side tests and returns structured results/console output. +- `POST /namespaces/{NAMESPACE}/localizarGatilhos` + - Used by: `vscode-objectscript.ccs.locateTriggers` (`src/ccs/commands/locateTriggers.ts`) + - Behavior: locates triggers and supports opening returned locations. + +## Reliability & UX + +- Use `requestTimeout` from `objectscript.ccs` settings and respect VS Code’s `http.proxyStrictSSL`. +- Prefer non-blocking UX: progress notifications for long calls, graceful fallback when CCS resolution fails (e.g., fall back to VS Code’s default definition). +- User-facing strings in this layer are typically PT-BR; keep tone consistent and actionable. + +## Logging & Errors + +- Use `logDebug/logInfo/logWarn/logError` (`src/ccs/core/logging.ts`) instead of ad-hoc output. +- For errors coming from HTTP calls, surface a short message to the user and log details only when `debugLogging` is enabled. + +## HTTP & Security + +- Create HTTP clients via `createHttpClient()` (`src/ccs/core/http.ts`); don’t instantiate `axios` directly elsewhere in this folder. +- Never log credentials, auth headers, or full URLs that could embed secrets.