project.txt

read https://github.com/tboy1337/Blinter

Project: Blinter VS Code Extension
1. High-Level Goal
Create a professional-grade Visual Studio Code extension that seamlessly integrates the "Blinter" linter for batch scripts (.bat, .cmd). The extension must provide a user experience on par with popular linters like ESLint or Pylint, offering automatic feedback, configuration, and helpful UI components. The Blinter tool is located at: https://github.com/tboy1337/Blinter

2. Core User Experience & Features
a. Automatic & On-Demand Linting
Automatic Linting (Core Feature): The extension should automatically lint files to provide real-time feedback. This should be configurable to run:
onSave: When the user saves the file (default behavior).
onType: As the user types, with a configurable delay (debounce) to prevent excessive runs.
On-Demand Linting: The user must also be able to trigger a linting pass manually. This command (blinter.run) should be accessible from:
The Command Palette (Ctrl+Shift+P).
A button in the Blinter side panel view.
The editor's right-click context menu.
b. User Configuration (settings.json)
To give users full control, the extension must contribute the following settings to settings.json:
blinter.enabled: A boolean to enable or disable the linter entirely.
blinter.runOn: A string ("onSave" or "onType") to control when linting occurs.
blinter.debounceDelay: A number (in milliseconds) for the onType delay.
blinter.pythonPath: (deprecated) This extension now requires the native `blinter.exe` in `bin/` and does not use Python. Remove references to Python when packaging.
blinter.rulesPath: An optional string path to a custom rules.json file, allowing users to override the bundled rules.
c. Rich UI Integration
Activity Bar Icon & View: An icon should appear in the Activity Bar only when a .bat or .cmd file is active ("when": "resourceLangId == bat"). Clicking it opens a simple view containing the "Run Blinter" button.
Status Bar Item: A status bar item (Blinter) should be visible when a batch file is open.
It should show a spinning icon ($(sync~spin)) while linting is in progress.
It should show a checkmark ($(check)) if linting completes with no errors, and an error icon ($(error)) if problems are found.
Clicking the status bar item should open the "Problems" panel.
Output Channel: For debugging and transparency, create a dedicated "Output Channel" named "Blinter". The extension should log the raw command being executed, the full output from blinter.py, and any internal errors here.
d. Advanced: Quick Fixes (Code Actions)
For a truly advanced experience, the extension should provide "Quick Fixes" for certain diagnostic errors.
Implement a CodeActionProvider that suggests automatic fixes for simple, unambiguous rules.
Example Idea: If Blinter has a rule for "inconsistent command casing" (e.g., flags eChO), a Quick Fix could suggest changing it to the standard echo. (This is a speculative rule, but illustrates the concept).
3. Linter Execution & Diagnostics
a. Execution Logic
The blinter.py script and its default rules.json must be bundled within the extension. The extension should be self-contained and not require a separate user installation of Blinter.
It must run blinter.py as a child process, respecting the blinter.pythonPath and blinter.rulesPath settings if they are configured.
Robust Error Handling: The extension must gracefully handle cases where Python isn't installed or the script crashes, showing an informative message to the user once.
b. Diagnostics and Problems
The extension must parse the stdout from the Blinter script ([SEVERITY] (CODE) -> DESCRIPTION on line LINE_NUMBER).
Map Blinter severities to vscode.DiagnosticSeverity: INFO -> Information, WARN -> Warning, ERROR/FATAL -> Error.
Create a vscode.Diagnostic for each reported issue and publish them to a DiagnosticCollection. This populates the "Problems" panel and creates editor squiggles.
The diagnostics for a file must be cleared before each new linting run.





project update:

Project: Blinter VSCode Debug & Lint Extension

### 1. High-Level Goal

Transform **Blinter** into a **VS Code debug extension** designed for **debugging and linting Batch (.bat/.cmd)** files, integrating seamlessly with the native **Run and Debug UI**.
The extension replaces its standalone “Run Blinter” button with full **native debugging integration** while preserving and enhancing **automatic linting, diagnostics, hovers, and quick fixes**.

The Blinter core engine is at: [https://github.com/tboy1337/Blinter](https://github.com/tboy1337/Blinter)

---

### 2. Core User Experience

#### a. Native Run & Debug Integration (Idea.md priority)

* The **Run and Debug** button on the VS Code sidebar launches Blinter automatically via a new debugger contribution (`type: "blinter-debug"`).
* Remove the standalone button and any custom Run command UI (`blinter.run`).
* Implement the inline **debug adapter** (using `lib/debugAdapterCore.js` + `DebugAdapterInlineImplementation`) that:

  * Spawns the Blinter process.
  * Captures and streams stdout/stderr to the **Debug Console**.
  * Parses the output for diagnostics and variable tracking.
* When a session starts:

  * Open a **side panel** titled “Blinter Output” within the Run and Debug view.
  * Parse and classify output into **Errors, Warnings, Undefined Variables**, and **Info**.
  * Display clickable links (e.g., `file.bat:123 — message`) that reveal the exact line in the editor.

---

#### b. Automatic and On-Demand Linting (from project.txt)

* The extension automatically lints active batch files in real-time.
* Configurable behaviors via `settings.json`:

  * `blinter.enabled`: toggle Blinter entirely.
  * `blinter.runOn`: `"onSave"` or `"onType"`.
  * `blinter.debounceDelay`: milliseconds for `onType` delay.
  * `blinter.rulesPath`: optional path to a custom rules.json.
* Real-time linting occurs independently of debugging mode, ensuring quick problem detection during normal editing.

---

#### c. Output Parsing, Variable Tracking, and Diagnostics

* Parse Blinter output to extract:

  * File paths, line numbers, severity, and message.
  * Variable definitions, modifications, and usage traces.
  * “Critical issues” (anti-patterns like undefined variables, empty labels, unreachable code).
* Store parsed issues in an internal map (`issuesStore`).
* Convert these to:

  * **Diagnostics** (`vscode.DiagnosticCollection`) visible in the Problems panel.
  * **Decorations** (highlight or underline) applied directly in the editor.
  * **Hover tooltips** that summarize errors or show variable traces.
* Diagnostics must update incrementally during debugging and clear on session termination.

Hover & Clickable Problem Display
* Hovering a flagged line displays:
  * Classification (Error/Warning/Info)
  * The detailed message
  * Optional variable trace, e.g., “Defined at foo.bat:15 → Modified at bar.bat:45”

* Clicking items in the side panel or Problems list should:
  * Focus the corresponding editor.
  * Scroll smoothly to the line.
  # Blinter VS Code Extension — Project Summary (polished)

  Source engine: https://github.com/tboy1337/Blinter

  Purpose
  -------
  Build a professional VS Code extension that provides linting and debugging for Windows batch scripts (.bat, .cmd) using the Blinter engine. The extension must feel native to VS Code: integrate with Run & Debug, surface diagnostics in Problems, provide quick fixes and hovers, and expose a clear configuration surface.

  Conflict resolution rule (authoritative)
  -------------------------------------
  When the original notes contain conflicting ideas, prefer the idea that appears later in the file. This cleaned document already applies that rule: later items (the "project update" section) take precedence over earlier, now-obsolete notes.

  High-level decisions (canonical)
  --------------------------------
  - The extension is a debug + linter extension that contributes a debugger type: `blinter-debug` (this is the canonical runtime type).
  - The extension bundles a native `blinter.exe` (or platform-appropriate binary) plus a default `rules.json`. It is self-contained and should not require the user to install Blinter separately.
  - The inline debug adapter model is used (via `lib/debugAdapterCore.js` + `vscode.DebugAdapterInlineImplementation`) so debug sessions stream stdout/stderr into the Debug Console and are parsed live.

  User-facing features (must-haves)
  --------------------------------
  - Automatic linting (configurable):
    - `blinter.runOn` = `"onSave"` (default) or `"onType"` (debounced by `blinter.debounceDelay`).
    - `blinter.enabled` boolean to disable/enable extension functionality.
    - `blinter.debounceDelay` number (ms) for `onType` mode.
    - `blinter.rulesPath` optional path to a custom rules.json that overrides bundled rules.

  - Native Run & Debug integration:
    - Contribute debugger type `blinter-debug` and a default `launch.json` example.
    - Starting a debug session launches the bundled Blinter binary and streams its output into the Debug Console and the extension's parser.

  - Diagnostics & editor integrations:
    - Parse Blinter output to produce `vscode.Diagnostic` items (Problems panel).
    - Map severities: INFO -> Information, WARN -> Warning, ERROR/FATAL -> Error.
    - Provide hover tooltips, editor decorations, and clickable links that reveal locations.

  - Side panel / webview:
    - Provide `blinter.outputSummary` as a WebviewViewProvider inside the Run & Debug container to show categorized issues (Errors/Warnings/Info) with clickable file:line entries.

  - Quick fixes:
    - Implement `CodeActionProvider` to offer deterministic fixes (e.g., normalize command casing, add simple missing initializations, remove redundant labels).

  Execution and debug adapter behavior
  -----------------------------------
  - Debug adapter: inline implementation wrapping `InlineDebugAdapterSession` in `lib/debugAdapterCore.js`. It must:
    - Spawn the bundled `blinter.exe` with configured args.
    - Stream stdout/stderr to the Debug Console and to the parser.
    - Incrementally update diagnostics and variable traces during a session.
  - PrepareForLaunch workflow:
    - Resolve `${file}` and workspace folders.
    - Validate target program exists.
    - Locate `blinter.exe` in `bin/` or `bins/` (support versioned names like `Blinter-v1.0.94.exe`).

  Parsing and diagnostics
  ----------------------
  - Parse each output line (legacy and detailed formats) into structured issues: { severity, code, description, filePath?, line?, details? }.
  - Maintain an internal `issuesStore` keyed by file path for incremental updates and flushing to `vscode.DiagnosticCollection`.
  - Ensure diagnostics for a file are cleared before each new run.

  Testing, logging and the mandatory progress file (critical)
  --------------------------------------------------------
  This project requires a strict, machine-readable `progress.txt` in the repository root. ALWAYS read `progress.txt` first before modifying any file. The file is the single source of truth for agent handoffs.

  `progress.txt` format (required):
  - It is a UTF-8 text file with append-only entries. Each entry must include these fields in this order, separated by a blank line between entries:
    1) ISO-8601 UTC timestamp (e.g. 2025-11-02T15:04:05Z)
    2) Agent/author name (human or bot)
    3) Short action/title (1 line)
    4) Files changed (comma-separated paths) or `NONE`
    5) Commands run (one per line) or `NONE`
    6) Artifacts produced (e.g., blinter.vsix, project_logs.log) or `NONE`
    7) Current test status summary (lint/unit/integration) or `UNKNOWN`
    8) Short notes and next steps (1-3 lines)

  Example entry:

  2025-11-02T15:04:05Z
  agent: copilot
  action: fixed debug adapter type and ran unit tests
  files: extension.js, package.json
  commands:
    npm run lint
    npm run test:unit
  artifacts: NONE
  tests: lint=warn-only, unit=10/10 pass, integration=not-run
  notes: updated debug type to `blinter-debug`; next: repackage VSIX and run integration tests

  Operational rules for agents
  ---------------------------
  - ALWAYS read `progress.txt` before changing files and after each prompt or noteworthy task completion. If you cannot read it, stop and ask the user.
  - After any code change or test run, append exactly one new `progress.txt` entry summarizing what changed and what to do next.
  - When running tests in CI/local, collect stdout+stderr into `project_logs.log`, summarize the results in `progress.txt`, then truncate or archive `project_logs.log`.
   - Before editing any file, append a "formatting snapshot" entry to `progress.txt` that captures the file's formatting and a small context snippet. The snapshot must contain these fields (exact order):
     1) filename (relative path)
     2) encoding (e.g., UTF-8)
     3) EOL (LF or CRLF)
     4) indentation (tabs or spaces + size, e.g., 2 spaces)
     5) trailing newline present (yes/no)
     6) total line count
     7) a 3-line sample showing the intended edit region (preceding, target, following lines)
     8) one-line intent summary (what the edit will change)
  
    Example formatting-snapshot entry (append to `progress.txt` before changing a file):

    formatting-snapshot: extension.js
    encoding: UTF-8
    eol: CRLF
    indentation: spaces=2
    trailing-newline: yes
    lines: 1104
    sample:
      const vscode = require('vscode');
      const path = require('path');
      const fs = require('fs');
    intent: update debug adapter registration from 'blinter' to 'blinter-debug'

   - Preserve file formatting when editing. Do not run automatic formatters or change EOLs/indentation unless the user explicitly requests it. If formatting changes are necessary, include a before-and-after formatting snapshot in `progress.txt`.

  Run/test helper (recommended)
  -----------------------------
  Create a batch helper `run_tests.bat` (not added here) with the contents below. Agents should run it via `cmd /c run_tests.bat` and capture the output.

  Contents for `run_tests.bat` (recommended):

    @echo off
    set LOGFILE=project_logs.log
    echo Running lint... > %LOGFILE%
    npm run lint >> %LOGFILE% 2>&1 || echo LINT_FAILED >> %LOGFILE%
    echo Running unit tests... >> %LOGFILE%
    npm run test:unit >> %LOGFILE% 2>&1 || echo UNIT_TESTS_FAILED >> %LOGFILE%
    echo Running integration tests... >> %LOGFILE%
    npm run test:integration >> %LOGFILE% 2>&1 || echo INTEGRATION_TESTS_FAILED >> %LOGFILE%

  Agent workflow for test runs (two options):
  - Option A (agent can execute commands): run `cmd /c run_tests.bat`, wait for completion, then parse `project_logs.log` and append a `progress.txt` entry summarizing results. Clear or move `project_logs.log` after parsing.
  - Option B (agent cannot run commands in environment): ask the user to run `cmd /c run_tests.bat` and upload/confirm `project_logs.log`. After the user confirms, parse and summarize into `progress.txt`.

  Deliverables checklist (authoritative)
  -------------------------------------
  - [x] Add `lib/debugAdapterCore.js` (inline debug adapter core) and unit tests.
  - [x] Refactor `extension.js` to register debug configuration, diagnostics, hover provider, decorations, and webview view provider.
  - [x] Update `package.json` with `blinter-debug` contribution and activation events.
  - [x] Implement quick fixes for common casing issues.
  - [ ] Add `run_tests.bat` to automate log capture and test runs.
  - [x] Document Run & Debug workflow and sample `launch.json` in `README.md` / `PACKAGING.md`.

  Notes and next actions (short)
  -----------------------------
  1. Ensure `progress.txt` exists and contains the most recent state before making changes.
  2. Create `run_tests.bat` in the repo root (if automation is required) and update this file when completed.
  3. Prefer `blinter-debug` as the canonical debug type across code and manifest.

  If anything in this file appears inconsistent with the repository, the source of truth is: the latest entry in `progress.txt` followed by this file. Agents should follow the `progress.txt` rules and then continue.