4 Commits

Author SHA1 Message Date
nvaldez 579f37f112 implement shell check 2026-09-29 14:33:29 +02:00
nvaldez e0ad912eb4 update todo with the audit 2026-09-29 10:44:57 +02:00
nvaldez a745ba92c1 update the spec 2026-09-29 10:10:20 +02:00
nvaldez c8b98dbbd6 windows bootstrap implemented 2026-09-29 10:04:57 +02:00
11 changed files with 1696 additions and 287 deletions
+1
View File
@@ -5,6 +5,7 @@ __pycache__/
# Virtual environments # Virtual environments
.venv/ .venv/
.venvs/
venv/ venv/
env/ env/
ENV/ ENV/
+25 -5
View File
@@ -1,10 +1,10 @@
--- ---
name: Fiona-Assistant Agent Rules name: Fiona-Assistant Agent Rules
version: 1.3.1 version: 1.3.2
title: LLM Agent Rules title: LLM Agent Rules
type: summary type: summary
created: 2025-09-23 created: 2025-09-23
updated: 2026-09-26 updated: 2026-09-29
tags: [agents, rules, guidelines, llm, ai] tags: [agents, rules, guidelines, llm, ai]
sources: [] sources: []
--- ---
@@ -90,7 +90,9 @@ AGENTS.md files (e.g. the llm-wiki template's `src/llm-wiki/AGENTS.md`).
### 3.1 Always Use Bootstrap for Environment ### 3.1 Always Use Bootstrap for Environment
> BEFORE any testing or development work, you MUST source the bootstrap script > BEFORE any testing or development work, you MUST load the bootstrap script
Linux / macOS (bash, must be sourced):
```bash ```bash
# Bare minimum - always run this first # Bare minimum - always run this first
@@ -106,6 +108,17 @@ source bootstrap --env <env_name> --python <version>
source bootstrap --env <env_name> -c source bootstrap --env <env_name> -c
``` ```
Windows (PowerShell, must be dot-sourced). This creates a repo-local venv
at `.venvs\<name>` with the Python launcher. It does not install pyenv.
```powershell
Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass
. .\bootstrap.ps1
. .\bootstrap.ps1 --env fiona_env
. .\bootstrap.ps1 --env <env_name> --python <version>
. .\bootstrap.ps1 --env <env_name> -c
```
**Rationale**: The bootstrap script sets up the Python virtual environment, **Rationale**: The bootstrap script sets up the Python virtual environment,
installs dependencies, and ensures a consistent development environment. installs dependencies, and ensures a consistent development environment.
All testing and development MUST happen within this environment. All testing and development MUST happen within this environment.
@@ -177,7 +190,8 @@ fiona-assistant/
│ └── install_packages.sh # Dependency installer │ └── install_packages.sh # Dependency installer
│ │
├── pyproject.toml # Project configuration ├── pyproject.toml # Project configuration
├── bootstrap # Environment setup ├── bootstrap # Environment setup (bash; source it)
├── bootstrap.ps1 # Environment setup (PowerShell; dot-source it)
└── README.md # Project documentation └── README.md # Project documentation
``` ```
@@ -302,6 +316,12 @@ git commit -m "test: add TDD tests for name/version extraction"
source bootstrap --env <env_name> source bootstrap --env <env_name>
``` ```
On Windows, dot-source the PowerShell script instead:
```powershell
. .\bootstrap.ps1 --env <env_name>
```
2. **Load Appropriate Skill** (if applicable) 2. **Load Appropriate Skill** (if applicable)
- Python tasks: Load `python-tdd` skill - Python tasks: Load `python-tdd` skill
- Wiki tasks: Load `llm-wiki` skill - Wiki tasks: Load `llm-wiki` skill
@@ -435,7 +455,7 @@ These rules **CAN** be overridden by:
| Task | Required Action | | Task | Required Action |
| ---- | -------------- | | ---- | -------------- |
| Any Python work | Load python-tdd skill | | Any Python work | Load python-tdd skill |
| Before testing | `source bootstrap` | | Before testing | `source bootstrap` (Windows: `. .\bootstrap.ps1`) |
| Changing functionality | Read [SPEC](./SPEC.md) first | | Changing functionality | Read [SPEC](./SPEC.md) first |
| Modifying code | Write tests first (TDD) | | Modifying code | Write tests first (TDD) |
| Before commit | Run tests + linters | | Before commit | Run tests + linters |
+15 -4
View File
@@ -81,12 +81,22 @@ python -m pip install fiona-assistant
``` ```
- **Create and activate the virtual environment:** - **Create and activate the virtual environment:**
```bash Linux / macOS:
```bash
source bootstrap --env fiona_env -c source bootstrap --env fiona_env -c
``` ```
> Make sure `fiona_env` is activated as pyenv before proceeding Windows (PowerShell):
```powershell
Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass
. .\bootstrap.ps1 --env fiona_env -c
```
> Make sure `fiona_env` is activated before proceeding. On Windows the
> environment lives in `.venvs\fiona_env`.
--- ---
@@ -282,7 +292,8 @@ fiona-assistant/
│ └── README.md # Development documentation │ └── README.md # Development documentation
│ │
├── pyproject.toml # Project configuration ├── pyproject.toml # Project configuration
├── bootstrap # Environment setup script ├── bootstrap # Environment setup script (bash)
├── bootstrap.ps1 # Environment setup script (PowerShell)
├── LICENSE # GPL-3.0-only ├── LICENSE # GPL-3.0-only
└── README.md # This file └── README.md # This file
``` ```
+281 -240
View File
@@ -1,9 +1,9 @@
--- ---
name: Fiona-Assistant Specification name: Fiona-Assistant Specification
version: 0.38.0 version: 0.39.0
title: Project Spec Sheet title: Project Spec Sheet
created: 2026-09-23 created: 2026-09-23
updated: 2026-09-28 updated: 2026-09-29
type: summary type: summary
--- ---
@@ -18,8 +18,10 @@ type: summary
- [2.2. `fiona-assistant librarian [directory]`](#22-fiona-assistant-librarian-directory) - [2.2. `fiona-assistant librarian [directory]`](#22-fiona-assistant-librarian-directory)
- [2.3. `fiona-assistant mdoctor [subcommand] [directory]`](#23-fiona-assistant-mdoctor-subcommand-directory) - [2.3. `fiona-assistant mdoctor [subcommand] [directory]`](#23-fiona-assistant-mdoctor-subcommand-directory)
- [2.4. `fiona-assistant python-ruff [subcommand] [directory]`](#24-fiona-assistant-python-ruff-subcommand-directory) - [2.4. `fiona-assistant python-ruff [subcommand] [directory]`](#24-fiona-assistant-python-ruff-subcommand-directory)
- [2.5. `fiona-assistant html-js-lint [subcommand] [directory]`](#25-fiona-assistant-html-js-lint-subcommand-directory) - [2.5. `fiona-assistant fmlint [subcommand] [directory]`](#25-fiona-assistant-fmlint-subcommand-directory)
- [2.6. `fiona-assistant wiki [subcommand] [directory]`](#26-fiona-assistant-wiki-subcommand-directory) - [2.6. `fiona-assistant json-lint [subcommand] [directory]`](#26-fiona-assistant-json-lint-subcommand-directory)
- [2.7. `fiona-assistant git [subcommand]`](#27-fiona-assistant-git-subcommand)
- [2.8. `fiona-assistant wiki [subcommand] [directory]`](#28-fiona-assistant-wiki-subcommand-directory)
- [3. llm-wiki Specifications](#3-llm-wiki-specifications) - [3. llm-wiki Specifications](#3-llm-wiki-specifications)
- [3.1. llm-wiki Lifecycle Management](#31-llm-wiki-lifecycle-management) - [3.1. llm-wiki Lifecycle Management](#31-llm-wiki-lifecycle-management)
- [3.1.1. `wiki init`](#311-wiki-init) - [3.1.1. `wiki init`](#311-wiki-init)
@@ -55,24 +57,24 @@ type: summary
- [4.9.5. Shared Sanity Runner Engine](#495-shared-sanity-runner-engine) - [4.9.5. Shared Sanity Runner Engine](#495-shared-sanity-runner-engine)
- [4.9.6. Progress Display](#496-progress-display) - [4.9.6. Progress Display](#496-progress-display)
- [4.10. toc-generator (Table of Contents)](#410-toc-generator-table-of-contents) - [4.10. toc-generator (Table of Contents)](#410-toc-generator-table-of-contents)
- [4.10.1. MD Frontmatter Tagging](#4101-md-frontmatter-tagging)
- [4.10.2. Per-File TOC Generation (`librarian toc file`)](#4102-per-file-toc-generation-librarian-toc-file) - [4.10.2. Per-File TOC Generation (`librarian toc file`)](#4102-per-file-toc-generation-librarian-toc-file)
- [4.10.3. MD Frontmatter Tagging](#4103-md-frontmatter-tagging)
- [4.11. fiona (CLI Entry Point)](#411-fiona-cli-entry-point) - [4.11. fiona (CLI Entry Point)](#411-fiona-cli-entry-point)
- [4.11.1. Wiki Root Discovery (`fiona-settings.json`)](#4111-wiki-root-discovery-fiona-settingsjson) - [4.11.1. Wiki Root Discovery (`fiona-settings.json`)](#4111-wiki-root-discovery-fiona-settingsjson)
- [4.10. json-lint (JSON Linter)](#410-json-lint-json-linter)
- [4.10.1. JSON Syntax Validation](#4101-json-syntax-validation)
- [4.10.2. JSON Style Rules](#4102-json-style-rules)
- [4.10.3. CLI Integration](#4103-cli-integration)
- [4.10.4. Sanity Integration](#4104-sanity-integration)
- [4.12. html-js-lint (HTML and JavaScript Linter)](#412-html-js-lint-html-and-javascript-linter) - [4.12. html-js-lint (HTML and JavaScript Linter)](#412-html-js-lint-html-and-javascript-linter)
- [4.12.1. HTML Validation](#4121-html-validation) - [4.12.1. HTML Validation](#4121-html-validation)
- [4.12.2. JavaScript Linting](#4122-javascript-linting) - [4.12.2. JavaScript Linting](#4122-javascript-linting)
- [4.12.3. CLI Integration](#4123-cli-integration) - [4.12.3. CLI Integration](#4123-cli-integration)
- [4.12.4. Configuration](#4124-configuration) - [4.12.4. Configuration](#4124-configuration)
- [4.12.5. Sanity Integration](#4125-sanity-integration) - [4.12.5. Sanity Integration](#4125-sanity-integration)
- [4.11. settings_manager (Settings Management)](#411-settings_manager-settings-management) - [4.13. json-lint (JSON Linter)](#413-json-lint-json-linter)
- [4.11.1. Interactive Setup (`fiona-assistant setup`)](#4111-interactive-setup-fiona-assistant-setup) - [4.13.1. JSON Syntax Validation](#4131-json-syntax-validation)
- [4.11.2. Contrast with `fiona-assistant init`](#4112-contrast-with-fiona-assistant-init) - [4.13.2. JSON Style Rules](#4132-json-style-rules)
- [4.13.3. CLI Integration](#4133-cli-integration)
- [4.13.4. Sanity Integration](#4134-sanity-integration)
- [4.14. settings_manager (Settings Management)](#414-settings_manager-settings-management)
- [4.14.1. Interactive Setup (`fiona-assistant setup`)](#4141-interactive-setup-fiona-assistant-setup)
- [4.14.2. Contrast with `fiona-assistant init`](#4142-contrast-with-fiona-assistant-init)
- [5. Project Infrastructure](#5-project-infrastructure) - [5. Project Infrastructure](#5-project-infrastructure)
- [5.1. Logging Library](#51-logging-library) - [5.1. Logging Library](#51-logging-library)
- [5.2. Documentation (medium priority)](#52-documentation-medium-priority) - [5.2. Documentation (medium priority)](#52-documentation-medium-priority)
@@ -160,10 +162,10 @@ reserve LLM tokens for creative and analytical work.
## 2. Current Capabilities ## 2. Current Capabilities
All commands below are implemented and reachable through the single All commands below are implemented and reachable through the single
`fiona-assistant` console script (section 4.9). Every optional `fiona-assistant` console script (section 4.11). Every optional
`[directory]` argument currently defaults to the current directory; `[directory]` argument currently defaults to the current directory;
the planned wiki root discovery [4.9.1](#491-failure-reporting) the planned wiki root discovery [4.11.1](#4111-wiki-root-discovery-fiona-settingsjson)
will replace that default with will replace that default with
the directory containing `fiona-settings.json`. the directory containing `fiona-settings.json`.
### 2.1. `fiona-assistant` ### 2.1. `fiona-assistant`
@@ -199,14 +201,34 @@ the directory containing `fiona-settings.json`.
- `chklint [directory]`: Lint Python sources with ruff and print an - `chklint [directory]`: Lint Python sources with ruff and print an
AI-friendly violation report (file, line:column, rule code). AI-friendly violation report (file, line:column, rule code).
### 2.5. `fiona-assistant html-js-lint [subcommand] [directory]` ### 2.5. `fiona-assistant fmlint [subcommand] [directory]`
- No subcommand: print the help and exit 1. - No subcommand: default to `chklint .`.
- `chklint [directory]`: Check HTML and JavaScript files for lint violations. - `chklint [directory]`: Validate markdown frontmatter
Supports `--json` flag for AI-friendly output format. ([4.2](#42-frontmatter-linter-fmlint)). The report lists violations
- `--fix`: Auto-fix certain violations where supported by underlying linters. and the command exits 0.
### 2.6. `fiona-assistant wiki [subcommand] [directory]` ### 2.6. `fiona-assistant json-lint [subcommand] [directory]`
- No subcommand: default to `chklint .`.
- `chklint [directory]`: Validate JSON syntax and style
([4.13](#413-json-lint-json-linter)).
- `fix [directory]`: Auto-fix indentation and trailing commas in place.
### 2.7. `fiona-assistant git [subcommand]`
Local git operations on an llm-wiki
([3.2](#32-git-version-control-for-llm-wiki)).
- No subcommand: print the git help and exit 1.
- `save --description TEXT`: Commit current edits.
- `snapshot <tag_name> --description TEXT`: Save, then create a tag.
- `restore <tag_name>`: New commit restoring the tagged tree.
- `clean`: Discard uncommitted edits.
- `undo`: Move back one commit. Fails when the working tree is dirty.
- `status`: Print a short git status.
### 2.8. `fiona-assistant wiki [subcommand] [directory]`
- No subcommand: print the wiki help and exit 1. - No subcommand: print the wiki help and exit 1.
- `init [directory]`: Initialize the directory as an llm-wiki by copying - `init [directory]`: Initialize the directory as an llm-wiki by copying
@@ -242,10 +264,10 @@ Notes:
### 3.1. llm-wiki Lifecycle Management ### 3.1. llm-wiki Lifecycle Management
> Status: Partially Implemented > Status: Implemented
> >
> Covers: `wiki init` (implemented, 3.1.1), `wiki update` (implemented, > Covers: `wiki init` (implemented, 3.1.1), `wiki update` (implemented,
> 3.1.2), `wiki sanity` (implemented, 3.1.3), `wiki graph` (planned, 3.1.4). > 3.1.2), `wiki sanity` (implemented, 3.1.3), `wiki graph` (implemented, 3.1.4).
#### 3.1.1. `wiki init` #### 3.1.1. `wiki init`
@@ -344,8 +366,8 @@ Run all validation checks over an llm-wiki directory in one command.
- *3.1.3.1.* Runs markdown lint (`mdoctor`), frontmatter lint (`fmlint`, 4.2), - *3.1.3.1.* Runs markdown lint (`mdoctor`), frontmatter lint (`fmlint`, 4.2),
Python lint (`python-ruff`), the custom markdown linter Python lint (`python-ruff`), the custom markdown linter
(`mdlinter`, 4.3.3), and any other registered linters (`mdlinter`, 4.3.3), JSON lint (`jsonlint`, 4.13), and any other
(shellcheck once 4.4 ships). registered linters (shellcheck once 4.6 ships).
- *acceptance*: Exits 0 on a clean wiki, non-zero on any violation. - *acceptance*: Exits 0 on a clean wiki, non-zero on any violation.
- *3.1.3.2.* Checks for dead links (relative and wiki-internal links resolving - *3.1.3.2.* Checks for dead links (relative and wiki-internal links resolving
to to
@@ -386,7 +408,7 @@ violation
[4.2](#42-frontmatter-linter-fmlint) [4.2](#42-frontmatter-linter-fmlint)
— required `name`/`version` frontmatter per — required `name`/`version` frontmatter per
[project agent rule 10.1](AGENTS.md#101-md-file-frontmatter)), `python-ruff`, [project agent rule 10.1](AGENTS.md#101-md-file-frontmatter)), `python-ruff`,
`mdlinter`. `mdlinter`, `jsonlint` ([4.13](#413-json-lint-json-linter)).
- *3.1.3.10.* The report mirrors run_sanity [4.9.3](#493-linter-report-format)/ - *3.1.3.10.* The report mirrors run_sanity [4.9.3](#493-linter-report-format)/
[4.9.4](#494-run-timing): failing checks' linter reports first (clean runs [4.9.4](#494-run-timing): failing checks' linter reports first (clean runs
print no report), a `Results:` print no report), a `Results:`
@@ -399,16 +421,14 @@ violation
#### 3.1.4. `wiki graph` #### 3.1.4. `wiki graph`
> Status: Partially Implemented > Status: Implemented
> >
> Covers: New module `src/wiki/graph_generator.py` and the > Covers: `src/wiki/graph_generator.py`,
> `src/wiki/templates/graph_template.html`, and the
> `fiona-assistant wiki graph` subcommand. > `fiona-assistant wiki graph` subcommand.
> >
> Phase 1 (Core): Link parser + graph builder + basic HTML output + basic CLI > Phases 1-4 are in that module and template: link parser, CLI,
> Phase 2 (CLI): Command integration with existing wiki subcommands > color and physics, and the BFS layout.
> Phase 3 (Features): Color spectrum, edge coloring, gravity force, click handlers
> Phase 4 (Polish): BFS layout + animated appearance + 360deg separation + clustering
> Status: Implemented
Generate an interactive Obsidian-style graph visualization showing connections between Generate an interactive Obsidian-style graph visualization showing connections between
markdown files based on internal links. The graph helps users visualize knowledge markdown files based on internal links. The graph helps users visualize knowledge
@@ -648,6 +668,7 @@ Operations:
| `restore` | Create a new commit restoring to `<tag_name>` state; does NOT modify history | | `restore` | Create a new commit restoring to `<tag_name>` state; does NOT modify history |
| `clean` | Discard current uncommitted edits; `git status` must be clean afterwards | | `clean` | Discard current uncommitted edits; `git status` must be clean afterwards |
| `undo` | Move back one commit. Error if the working tree is dirty; run `clean` first | | `undo` | Move back one commit. Error if the working tree is dirty; run `clean` first |
| `status` | Print a short git status. Does not change the repository |
#### 3.2.1. Backup Script #### 3.2.1. Backup Script
@@ -785,7 +806,7 @@ ignored by MD025 |
| `md060.enabled` | Implemented | False; table style rule diverges from Node.js | `md060.enabled` | Implemented | False; table style rule diverges from Node.js
| |
| `python.ruff` | Reserved | Unused placeholder for future ruff config | `python.ruff` | Reserved | Unused placeholder for future ruff config
[4.3](#43-custom-linter-framework) | [4.5](#45-python-ruff-python-lint) |
| `markdown.toc_generator.max_depth_from_file` | Implemented | Header level cap | `markdown.toc_generator.max_depth_from_file` | Implemented | Header level cap
per file in TOCs | per file in TOCs |
| `markdown.toc_generator.max_depth_from_dir` | Implemented | Subfolder | `markdown.toc_generator.max_depth_from_dir` | Implemented | Subfolder
@@ -827,13 +848,13 @@ Related but separate: the sanity coverage gate lives in
not in `fiona-settings.json`. The template copy shipped with the not in `fiona-settings.json`. The template copy shipped with the
package is `src/llm-wiki/fiona-settings.json`; `wiki init` copies it package is `src/llm-wiki/fiona-settings.json`; `wiki init` copies it
into user wikis [3.1.1](#311-wiki-init) into user wikis [3.1.1](#311-wiki-init)
and it marks the wiki root [4.9.1](#491-failure-reporting). and it marks the wiki root [4.11.1](#4111-wiki-root-discovery-fiona-settingsjson).
--- ---
### 4.2. Frontmatter Linter (fmlint) ### 4.2. Frontmatter Linter (fmlint)
> Status: Planned > Status: Implemented
> >
> Covers: `src/customlinter/fmlint.py`. A custom linter specifically for > Covers: `src/customlinter/fmlint.py`. A custom linter specifically for
> validating markdown file frontmatter against project requirements. > validating markdown file frontmatter against project requirements.
@@ -842,7 +863,7 @@ into user wikis [3.1.1](#311-wiki-init)
#### 4.2.1. Frontmatter Validation #### 4.2.1. Frontmatter Validation
> Status: Planned > Status: Implemented
Validate that all markdown files in an llm-wiki directory have proper Validate that all markdown files in an llm-wiki directory have proper
frontmatter with required fields. frontmatter with required fields.
@@ -865,22 +886,22 @@ editing |
| `sources` | No | Source file references (e.g. `raw/articles/source-name.md`) | | `sources` | No | Source file references (e.g. `raw/articles/source-name.md`) |
| `confidence` / `contested` / `contradictions` | No | Quality signals | | `confidence` / `contested` / `contradictions` | No | Quality signals |
- *4.2.1.1.* `NOT_IMPLEMENTED` Scan all `.md` files in a directory tree for frontmatter presence. - *4.2.1.1.* Scan all `.md` files in a directory tree for frontmatter presence.
- *acceptance*: A md file missing `name` field is reported with file path and - *acceptance*: A md file missing `name` field is reported with file path and
missing field. missing field.
- *4.2.1.2.* `NOT_IMPLEMENTED` Validate that the required fields `name` and `version` are present - *4.2.1.2.* Validate that the required fields `name` and `version` are present
(the minimum for source control per (the minimum for source control per
[project agent rule 10.1](AGENTS.md#101-md-file-frontmatter)). All other [project agent rule 10.1](AGENTS.md#101-md-file-frontmatter)). All other
fields, including `title`, are optional. fields, including `title`, are optional.
- *acceptance*: A md file missing `version` field is reported with file path - *acceptance*: A md file missing `version` field is reported with file path
and missing field. and missing field.
- *4.2.1.3.* `NOT_IMPLEMENTED` Support configurable required fields via `fiona-settings.json` for - *4.2.1.3.* Support configurable required fields via `fiona-settings.json` for
different file types (e.g., `type: toc` files may have different requirements different file types (e.g., `type: toc` files may have different requirements
. .
- *acceptance*: A md file with `name` and `version` but no `title` passes - *acceptance*: A md file with `name` and `version` but no `title` passes
validation validation
(`title` is optional). (`title` is optional).
- *4.2.1.4.* `NOT_IMPLEMENTED` Report violations in AI-friendly format: file path, missing fields - *4.2.1.4.* Report violations in AI-friendly format: file path, missing fields
and and
line number (if known). Violation messages use the format `<code> - line number (if known). Violation messages use the format `<code> -
<message>`. <message>`.
@@ -888,62 +909,62 @@ validation
at the start of the file (line 1), so `1:1` prefix is redundant. at the start of the file (line 1), so `1:1` prefix is redundant.
- *acceptance*: A md file with no frontmatter at all is reported as missing - *acceptance*: A md file with no frontmatter at all is reported as missing
all required fields. all required fields.
- *4.2.1.5.* `NOT_IMPLEMENTED` Handle files without frontmatter (report as missing all required - *4.2.1.5.* Handle files without frontmatter (report as missing all required
fields). fields).
- *acceptance*: A md file with malformed YAML frontmatter is reported with - *acceptance*: A md file with malformed YAML frontmatter is reported with
parse error details. parse error details.
- *4.2.1.6.* `NOT_IMPLEMENTED` Handle files with malformed YAML frontmatter (report as parse - *4.2.1.6.* Handle files with malformed YAML frontmatter (report as parse
error). error).
- *acceptance*: Running on a directory with all valid frontmatter reports no - *acceptance*: Running on a directory with all valid frontmatter reports no
violations. violations.
- *4.2.1.7.* `NOT_IMPLEMENTED` Respect `.gitignore` and read-only zones (`personal/`, `raw/`). - *4.2.1.7.* Respect `.gitignore` and read-only zones (`personal/`, `raw/`).
- *acceptance*: The linter integrates with `wiki sanity` - *acceptance*: The linter integrates with `wiki sanity`
[3.1.3](#313-wiki-sanity) and `run_sanity.py` [4.9](#49-test-and-sanity-runners). [3.1.3](#313-wiki-sanity) and `run_sanity.py` [4.9](#49-test-and-sanity-runners).
#### 4.2.2. CLI Integration #### 4.2.2. CLI Integration
> Status: Planned > Status: Implemented
Provide CLI access to the frontmatter linter via `fiona-assistant`. Provide CLI access to the frontmatter linter via `fiona-assistant`.
- *4.2.2.1.* `NOT_IMPLEMENTED` `fiona-assistant fmlint chklint [directory]` scans for frontmatter - *4.2.2.1.* `fiona-assistant fmlint chklint [directory]` scans for frontmatter
violations. violations.
- *acceptance*: Running `fiona-assistant fmlint` on a directory with invalid - *acceptance*: Running `fiona-assistant fmlint` on a directory with invalid
frontmatter frontmatter
produces a structured violation report. produces a structured violation report.
- *4.2.2.2.* `NOT_IMPLEMENTED` `fiona-assistant fmlint` with no subcommand defaults to `chklint`. - *4.2.2.2.* `fiona-assistant fmlint` with no subcommand defaults to `chklint`.
- *acceptance*: Running on a clean directory reports no violations. - *acceptance*: Running on a clean directory reports no violations.
- *4.2.2.3.* `NOT_IMPLEMENTED` Output format matches other linters: AI-friendly violation report - *4.2.2.3.* Output format matches other linters: AI-friendly violation report
with with
file paths, line numbers, and rule codes. file paths, line numbers, and rule codes.
- *4.2.2.4.* `NOT_IMPLEMENTED` Exit code 0 even with violations (consistent with other linters). - *4.2.2.4.* Exit code 0 even with violations (consistent with other linters).
#### 4.2.3. Settings Integration #### 4.2.3. Settings Integration
> Status: Planned > Status: Implemented
Configure frontmatter linter behavior via `fiona-settings.json`. Configure frontmatter linter behavior via `fiona-settings.json`.
- *4.2.3.1.* `NOT_IMPLEMENTED` Load required fields from `markdown.frontmatter.required_fields` in - *4.2.3.1.* Load required fields from `markdown.frontmatter.required_fields` in
`fiona-settings.json` (default: `['name', 'version']`). `fiona-settings.json` (default: `['name', 'version']`).
- *acceptance*: Changing required fields in `fiona-settings.json` changes - *acceptance*: Changing required fields in `fiona-settings.json` changes
validation validation
behavior on the next run. behavior on the next run.
- *4.2.3.2.* `NOT_IMPLEMENTED` Support per-type requirements: `markdown.frontmatter - *4.2.3.2.* Support per-type requirements: `markdown.frontmatter
type_requirements` type_requirements`
maps file types to their specific required fields. maps file types to their specific required fields.
- *acceptance*: Disabling the linter via settings skips frontmatter - *acceptance*: Disabling the linter via settings skips frontmatter
validation. validation.
- *4.2.3.3.* `NOT_IMPLEMENTED` Allow disabling the linter via `markdown.frontmatter.enabled` - *4.2.3.3.* Allow disabling the linter via `markdown.frontmatter.enabled`
(default: true). (default: true).
- *acceptance*: Rules listed in `ignore_rules` are not reported as violations. - *acceptance*: Rules listed in `ignore_rules` are not reported as violations.
- *4.2.3.4.* `NOT_IMPLEMENTED` Support ignoring specific violation rules via `markdown - *4.2.3.4.* Support ignoring specific violation rules via `markdown
frontmatter.ignore_rules` frontmatter.ignore_rules`
(e.g., `['FML002']` to ignore missing frontmatter). (e.g., `['FML002']` to ignore missing frontmatter).
- *acceptance*: Files matching patterns in `ignore_file` are skipped during - *acceptance*: Files matching patterns in `ignore_file` are skipped during
linting. linting.
- *4.2.3.5.* `NOT_IMPLEMENTED` Support ignoring specific file patterns via `markdown.frontmatter - *4.2.3.5.* Support ignoring specific file patterns via `markdown.frontmatter
ignore_file` ignore_file`
(e.g., `['*/AGENTS.md', '*/README.md']` to skip certain files). (e.g., `['*/AGENTS.md', '*/README.md']` to skip certain files).
@@ -1187,7 +1208,7 @@ decision; do not implement until the tagging format is specified.
> >
> Covers: `src/run_tests.py` (TestRunner) and `src/run_sanity.py` > Covers: `src/run_tests.py` (TestRunner) and `src/run_sanity.py`
> (parallel pytests with a coverage gate, markdownlint, frontmatter, > (parallel pytests with a coverage gate, markdownlint, frontmatter,
> ruff, and pycustomlint checks; see 4.9.1 to 4.9.6). > ruff, pycustomlint, and jsonlint checks; see 4.9.1 to 4.9.6).
#### 4.9.1. Failure Reporting #### 4.9.1. Failure Reporting
@@ -1257,8 +1278,8 @@ the verdict
> Status: Implemented > Status: Implemented
> >
> Every linter check in the sanity runner (markdownlint, frontmatter_lint, > Every linter check in the sanity runner (markdownlint, frontmatter_lint,
> pycustomlint, mdlinter) prints the same AI-friendly report structure so the > pycustomlint, mdlinter, jsonlint) prints the same AI-friendly report
> reports are diffable across linters. > structure so the reports are diffable across linters.
- *4.9.3.1.* The report starts with a `<Linter Name> Violations` header followed - *4.9.3.1.* The report starts with a `<Linter Name> Violations` header followed
by `TARGET: <scanned path>`. by `TARGET: <scanned path>`.
@@ -1452,32 +1473,6 @@ section of
- `--non-recursive` still forces direct files only regardless of - `--non-recursive` still forces direct files only regardless of
`max_depth_from_dir` `max_depth_from_dir`
#### 4.10.1. MD Frontmatter Tagging
> Status: Partially Implemented
Tag md files with metadata used for version control and quality
signals; the `version` tag feeds the TOC entries above.
| Tag | Status | Purpose |
| --- | ------ | ------- |
| `version` | Implemented | Source control, `wiki update` change detection, TOC
display |
| `date` | Planned | Creation/last-update timestamps maintained by tooling |
| `confidence` | Planned | Quality signal (e.g. high/medium/low) on concept
notes |
| `contested` | Planned | Boolean flag marking notes with disputed claims |
- *4.10.1.1.* Frontmatter is validated by the `md_frontmatter` module (see
[4.8](#48-librarian-content-management)).
- *acceptance*: A concept note missing `confidence` is flagged by `wiki sanity`
[3.1.3](#313-wiki-sanity).
- *4.10.1.2.* Tags follow the canonical frontmatter schema (see
[4.2.1](#421-frontmatter-validation)): `name` and
`version` are required, `title` and all other fields are optional.
- *4.10.1.3.* `wiki sanity` [3.1.3](#313-wiki-sanity)
warns on files missing required tags.
#### 4.10.2. Per-File TOC Generation (`librarian toc file`) #### 4.10.2. Per-File TOC Generation (`librarian toc file`)
> Status: Implemented > Status: Implemented
@@ -1576,6 +1571,30 @@ reports an
A file without an H1 is skipped with `skipped ... (no H1 heading)` A file without an H1 is skipped with `skipped ... (no H1 heading)`
and left unmodified. and left unmodified.
#### 4.10.3. MD Frontmatter Tagging
> Status: Partially Implemented
Tag md files with metadata used for version control and quality
signals; the `version` tag feeds the TOC entries above.
| Tag | Status | Purpose |
| --- | ------ | ------- |
| `version` | Implemented | Source control, `wiki update` change detection, TOC display |
| `date` | Planned | Creation/last-update timestamps maintained by tooling |
| `confidence` | Planned | Quality signal (e.g. high/medium/low) on concept notes |
| `contested` | Planned | Boolean flag marking notes with disputed claims |
- *4.10.3.1.* Frontmatter is validated by the `md_frontmatter` module (see
[4.8](#48-librarian-content-management)).
- *acceptance*: A concept note missing `confidence` is flagged by `wiki sanity`
[3.1.3](#313-wiki-sanity).
- *4.10.3.2.* Tags follow the canonical frontmatter schema (see
[4.2.1](#421-frontmatter-validation)): `name` and
`version` are required, `title` and all other fields are optional.
- *4.10.3.3.* `wiki sanity` [3.1.3](#313-wiki-sanity)
warns on files missing required tags.
--- ---
### 4.11. fiona (CLI Entry Point) ### 4.11. fiona (CLI Entry Point)
@@ -1586,15 +1605,17 @@ reports an
> dispatches to the tool modules so every tool is reachable through one > dispatches to the tool modules so every tool is reachable through one
> command. Each tool also keeps its standalone CLI; `librarian` and > command. Each tool also keeps its standalone CLI; `librarian` and
> `mdoctor` are installed as console scripts, while `python-ruff` is > `mdoctor` are installed as console scripts, while `python-ruff` is
> available only through `fiona-assistant`. All dispatch modules > available only through `fiona-assistant`. `fmlint`, `json-lint`, and
> (`fiona`, `python_ruff`) ship in the wheel. > the `git` subcommands are also only through `fiona-assistant`.
> Dispatch modules `fiona`, `python_ruff`, `customlinter`, `wiki`, and
> `gittool` ship in the wheel.
Command tree: Command tree:
| Command | Behavior | | Command | Behavior |
| ------- | -------- | | ------- | -------- |
| `fiona-assistant librarian [directory]` | List files via librarian | `fiona-assistant librarian [directory]` | List files via librarian
[4.6](#46-shellcheck-library) | [4.8](#48-librarian-content-management) |
| `fiona-assistant librarian list [directory]` | Same as above | | `fiona-assistant librarian list [directory]` | Same as above |
| `fiona-assistant librarian toc [directory]` | Generate a TOC | `fiona-assistant librarian toc [directory]` | Generate a TOC
[4.10](#410-toc-generator-table-of-contents) | [4.10](#410-toc-generator-table-of-contents) |
@@ -1604,8 +1625,14 @@ Command tree:
[4.10.2](#4102-per-file-toc-generation-librarian-toc-file) | [4.10.2](#4102-per-file-toc-generation-librarian-toc-file) |
| `fiona-assistant mdoctor [args]` | Delegate to the mdoctor CLI; defaults to | `fiona-assistant mdoctor [args]` | Delegate to the mdoctor CLI; defaults to
`chklint .` | `chklint .` |
| `fiona-assistant fmlint [args]` | Frontmatter lint; defaults to `chklint .`
[4.2](#42-frontmatter-linter-fmlint) |
| `fiona-assistant python-ruff [args]` | Delegate to the python-ruff CLI; | `fiona-assistant python-ruff [args]` | Delegate to the python-ruff CLI;
defaults to `chklint .` | defaults to `chklint .` |
| `fiona-assistant json-lint [args]` | JSON lint; defaults to `chklint .`
[4.13](#413-json-lint-json-linter) |
| `fiona-assistant git save/snapshot/restore/clean/undo/status` | Wiki git
operations [3.2](#32-git-version-control-for-llm-wiki) |
| `fiona-assistant wiki init [directory]` | Initialize an llm-wiki | `fiona-assistant wiki init [directory]` | Initialize an llm-wiki
[3.1.1](#311-wiki-init) | [3.1.1](#311-wiki-init) |
| `fiona-assistant wiki check-update [directory]` | Check for core-file updates | `fiona-assistant wiki check-update [directory]` | Check for core-file updates
@@ -1614,6 +1641,8 @@ defaults to `chklint .` |
[3.1.2](#312-wiki-update) | [3.1.2](#312-wiki-update) |
| `fiona-assistant wiki sanity [directory]` | Run all sanity checks | `fiona-assistant wiki sanity [directory]` | Run all sanity checks
[3.1.3](#313-wiki-sanity) | [3.1.3](#313-wiki-sanity) |
| `fiona-assistant wiki graph [directory]` | Write the link graph
[3.1.4](#314-wiki-graph) |
- *4.11.1.* With no subcommand, print help and exit 0. - *4.11.1.* With no subcommand, print help and exit 0.
- *acceptance*: Each subcommand behaves identically to the corresponding - *acceptance*: Each subcommand behaves identically to the corresponding
@@ -1660,112 +1689,14 @@ directory,
--- ---
### 4.10. json-lint (JSON Linter)
> Status: Planned
>
> Covers: `src/json_lint/`. A JSON linter and checker that validates
> JSON syntax and applies configurable style rules. Uses existing Python
> libraries (`json` module for parsing, potentially `json5` or similar for
> extended syntax support).
#### 4.10.1. JSON Syntax Validation
> Status: Planned
Validate that JSON files have correct syntax and are parseable.
- *4.10.1.1.* `NOT_IMPLEMENTED` Use Python's standard `json` module for syntax validation.
- *acceptance*: A JSON file with a syntax error (e.g., missing comma,
unquoted key) is
reported with file path and error location.
- *4.10.1.2.* `NOT_IMPLEMENTED` Check that all JSON files in the target directory tree are valid
JSON.
- *acceptance*: A JSON file with valid syntax but no style violations reports
no errors.
- *4.10.1.3.* `NOT_IMPLEMENTED` Report syntax errors with file path, line number, and column
position.
- *acceptance*: Running on a directory with no JSON files produces no errors.
- *4.10.1.4.* `NOT_IMPLEMENTED` Handle files with `.json` extension by default; support
configurable
extensions via settings.
- *4.10.1.5.* `NOT_IMPLEMENTED` Respect `.gitignore` and read-only zones (`personal/`, `raw/`).
#### 4.10.2. JSON Style Rules
> Status: Planned
Apply configurable style rules to JSON files.
- *4.10.2.1.* `NOT_IMPLEMENTED` Check indentation: tabs should be converted to spaces, with
configurable
indent length (default: 2 spaces per the project standard).
- *acceptance*: A JSON file with tab indentation when `indent: "space"` and
`indent_len: 2`
is configured reports a style violation.
- *4.10.2.2.* `NOT_IMPLEMENTED` Check trailing commas (optional based on settings).
- *4.10.2.3.* `NOT_IMPLEMENTED` Check key ordering (optional based on settings).
- *acceptance*: A JSON file with 4-space indentation when `indent_len: 2` is
configured
reports a style violation.
- *4.10.2.4.* `NOT_IMPLEMENTED` Check for duplicate keys in objects.
- *acceptance*: A JSON file with duplicate keys is reported as a violation.
- *4.10.2.5.* `NOT_IMPLEMENTED` Load style rules from the `json` section of `fiona-settings.json`:
- `indent`: `"space"` or `"tab"` (default: `"space"`)
- `indent_len`: number of spaces for indentation (default: 2)
- `trailing_commas`: bool, whether to allow trailing commas (default: false)
- `require_key_order`: bool, whether object keys must be sorted
(default: false)
- Additional rules can be added without code changes via configuration.
- *4.10.2.6.* `NOT_IMPLEMENTED` A missing `json` section in settings uses sensible defaults.
#### 4.10.3. CLI Integration
> Status: Planned
Provide CLI access to the JSON linter via `fiona-assistant`.
- *4.10.3.1.* `NOT_IMPLEMENTED` `fiona-assistant json-lint chklint [directory]` scans for JSON
violations.
- *acceptance*: Running `fiona-assistant json-lint` on a directory with
invalid JSON
produces a structured violation report.
- *4.10.3.2.* `NOT_IMPLEMENTED` `fiona-assistant json-lint` with no subcommand defaults to
`chklint .`.
- *acceptance*: Running on a clean directory reports no violations.
- *4.10.3.3.* `NOT_IMPLEMENTED` Output format matches other linters: AI-friendly violation report
with
file paths, line numbers, column numbers, and rule codes.
- *4.10.3.4.* `NOT_IMPLEMENTED` Exit code 0 even with violations (consistent with other linters).
- *4.10.3.5.* `NOT_IMPLEMENTED` Support `--fix` flag to auto-fix certain violations (indentation,
trailing
commas) in place.
- *acceptance*: Running with `--fix` on a file with fixable violations
corrects the file
and reports the number of fixed files.
#### 4.10.4. Sanity Integration
> Status: Planned
Integrate the JSON linter into the sanity checker.
- *4.10.4.1.* `NOT_IMPLEMENTED` `run_sanity.py` runs `json-lint chklint` on the codebase.
- *acceptance*: A JSON file with violations causes `run_sanity.py` to report
JSON lint
failures.
- *4.10.4.2.* `NOT_IMPLEMENTED` `wiki sanity` [3.1.3](#313-wiki-sanity)
runs `json-lint chklint` on the wiki directory.
- *acceptance*: `wiki sanity` [3.1.3](#313-wiki-sanity)
reports JSON violations alongside other linter violations.
- *4.10.4.3.* `NOT_IMPLEMENTED` JSON lint violations are reported in the aggregated sanity output.
---
### 4.12. html-js-lint (HTML and JavaScript Linter) ### 4.12. html-js-lint (HTML and JavaScript Linter)
> Status: Planned > Status: Planned
> >
> `pyproject.toml` still lists package `html_js_lint` and a
> `html-js-lint` console script. That directory does not exist.
> Remove both entries until this section is implemented.
>
> Covers: `src/html_js_lint/`. An HTML and JavaScript linter that validates > Covers: `src/html_js_lint/`. An HTML and JavaScript linter that validates
> HTML syntax and structure, and JavaScript code quality. Uses existing Python > HTML syntax and structure, and JavaScript code quality. Uses existing Python
> libraries where available: `html5validator` for HTML validation (W3C standard, > libraries where available: `html5validator` for HTML validation (W3C standard,
@@ -1875,78 +1806,181 @@ Integrate the HTML and JavaScript linter into the sanity checker.
--- ---
### 4.11. settings_manager (Settings Management)
### 4.13. json-lint (JSON Linter)
> Status: Implemented
>
> Covers: `src/customlinter/jsonlint.py`. A JSON linter and checker that validates
> JSON syntax and applies configurable style rules. Uses existing Python
> libraries (`json` module for parsing, potentially `json5` or similar for
> extended syntax support).
#### 4.13.1. JSON Syntax Validation
> Status: Implemented
Validate that JSON files have correct syntax and are parseable.
- *4.13.1.1.* Use Python's standard `json` module for syntax validation.
- *acceptance*: A JSON file with a syntax error (e.g., missing comma,
unquoted key) is
reported with file path and error location.
- *4.13.1.2.* Check that all JSON files in the target directory tree are valid
JSON.
- *acceptance*: A JSON file with valid syntax but no style violations reports
no errors.
- *4.13.1.3.* Report syntax errors with file path, line number, and column
position.
- *acceptance*: Running on a directory with no JSON files produces no errors.
- *4.13.1.4.* Handle files with `.json` extension by default; support
configurable
extensions via settings.
- *4.13.1.5.* Respect `.gitignore` and read-only zones (`personal/`, `raw/`).
#### 4.13.2. JSON Style Rules
> Status: Implemented
Apply configurable style rules to JSON files.
- *4.13.2.1.* Check indentation: tabs should be converted to spaces, with
configurable
indent length (default: 2 spaces per the project standard).
- *acceptance*: A JSON file with tab indentation when `indent: "space"` and
`indent_len: 2`
is configured reports a style violation.
- *4.13.2.2.* Check trailing commas (optional based on settings).
- *4.13.2.3.* Check key ordering (optional based on settings).
- *acceptance*: A JSON file with 4-space indentation when `indent_len: 2` is
configured
reports a style violation.
- *4.13.2.4.* Check for duplicate keys in objects.
- *acceptance*: A JSON file with duplicate keys is reported as a violation.
- *4.13.2.5.* Load style rules from the `json` section of `fiona-settings.json`:
- `indent`: `"space"` or `"tab"` (default: `"space"`)
- `indent_len`: number of spaces for indentation (default: 2)
- `trailing_commas`: bool, whether to allow trailing commas (default: false)
- `require_key_order`: bool, whether object keys must be sorted
(default: false)
- Additional rules can be added without code changes via configuration.
- *4.13.2.6.* A missing `json` section in settings uses sensible defaults.
#### 4.13.3. CLI Integration
> Status: Implemented
Provide CLI access to the JSON linter via `fiona-assistant`.
- *4.13.3.1.* `fiona-assistant json-lint chklint [directory]` scans for JSON
violations.
- *acceptance*: Running `fiona-assistant json-lint` on a directory with
invalid JSON
produces a structured violation report.
- *4.13.3.2.* `fiona-assistant json-lint` with no subcommand defaults to
`chklint .`.
- *acceptance*: Running on a clean directory reports no violations.
- *4.13.3.3.* Output format matches other linters: AI-friendly violation report
with
file paths, line numbers, column numbers, and rule codes.
- *4.13.3.4.* Exit code 0 even with violations (consistent with other linters).
- *4.13.3.5.* Support `--fix` flag to auto-fix certain violations (indentation,
trailing
commas) in place.
- *acceptance*: Running with `--fix` on a file with fixable violations
corrects the file
and reports the number of fixed files.
#### 4.13.4. Sanity Integration
> Status: Implemented
Integrate the JSON linter into the sanity checker.
- *4.13.4.1.* `run_sanity.py` runs `json-lint chklint` on the codebase.
- *acceptance*: A JSON file with violations causes `run_sanity.py` to report
JSON lint
failures.
- *4.13.4.2.* `wiki sanity` [3.1.3](#313-wiki-sanity)
runs `json-lint chklint` on the wiki directory.
- *acceptance*: `wiki sanity` [3.1.3](#313-wiki-sanity)
reports JSON violations alongside other linter violations.
- *4.13.4.3.* JSON lint violations are reported in the aggregated sanity output.
---
### 4.14. settings_manager (Settings Management)
> Status: Planned > Status: Planned
Covers: `src/fiona/settings_manager.py`. Provides interactive and Covers: `src/fiona/settings_manager.py`. Provides interactive and
non-interactive settings management for fiona-assistant. non-interactive settings management for fiona-assistant.
#### 4.11.1. Interactive Setup (`fiona-assistant setup`) #### 4.14.1. Interactive Setup (`fiona-assistant setup`)
> Status: Planned > Status: Planned
Run an interactive setup utility to configure fiona-assistant settings. Run an interactive setup utility to configure fiona-assistant settings.
- *4.11.1.1.* `NOT_IMPLEMENTED` Present all configurable settings from `fiona-settings.json` to - *4.14.1.1.* `NOT_IMPLEMENTED` Present all configurable settings from `fiona-settings.json` to
the user the user
- *acceptance*: Running `fiona-assistant setup` with no arguments starts the - *acceptance*: Running `fiona-assistant setup` with no arguments starts the
interactive flow interactive flow
- *4.11.1.2.* `NOT_IMPLEMENTED` Allow user to enable/disable boolean settings by checking or - *4.14.1.2.* `NOT_IMPLEMENTED` Allow user to enable/disable boolean settings by checking or
unchecking unchecking
- *acceptance*: User can navigate through all settings with Enter to accept - *acceptance*: User can navigate through all settings with Enter to accept
defaults defaults
- *4.11.1.3.* `NOT_IMPLEMENTED` Allow user to add custom values for string/integer settings where - *4.14.1.3.* `NOT_IMPLEMENTED` Allow user to add custom values for string/integer settings where
applicable applicable
- *acceptance*: User can toggle boolean settings (check/uncheck) - *acceptance*: User can toggle boolean settings (check/uncheck)
- *4.11.1.4.* `NOT_IMPLEMENTED` Provide a complete path where user can press Enter through all - *4.14.1.4.* `NOT_IMPLEMENTED` Provide a complete path where user can press Enter through all
prompts to prompts to
accept all defaults without modification accept all defaults without modification
- *acceptance*: User can input custom values for string/integer settings - *acceptance*: User can input custom values for string/integer settings
- *4.11.1.5.* `NOT_IMPLEMENTED` Display current values for each setting before prompting - *4.14.1.5.* `NOT_IMPLEMENTED` Display current values for each setting before prompting
- *4.11.1.6.* `NOT_IMPLEMENTED` Support non-interactive mode via flags (e.g., `--yes`, - *4.14.1.6.* `NOT_IMPLEMENTED` Support non-interactive mode via flags (e.g., `--yes`,
`--default`) for `--default`) for
AI agents to run deterministically AI agents to run deterministically
- *acceptance*: All inputs are validated before saving to settings file - *acceptance*: All inputs are validated before saving to settings file
- *4.11.1.7.* `NOT_IMPLEMENTED` Validate all inputs before saving - *4.14.1.7.* `NOT_IMPLEMENTED` Validate all inputs before saving
- *acceptance*: Non-interactive mode applies all defaults without prompts - *acceptance*: Non-interactive mode applies all defaults without prompts
- *4.11.1.8.* `NOT_IMPLEMENTED` Write validated settings to `fiona-settings.json` in the wiki root - *4.14.1.8.* `NOT_IMPLEMENTED` Write validated settings to `fiona-settings.json` in the wiki root
- *acceptance*: Exit code 0 on successful completion, non-zero on validation - *acceptance*: Exit code 0 on successful completion, non-zero on validation
error or failure error or failure
- *4.11.1.9.* `NOT_IMPLEMENTED` Handle missing or corrupted settings files gracefully - *4.14.1.9.* `NOT_IMPLEMENTED` Handle missing or corrupted settings files gracefully
- *acceptance*: Running `fiona-assistant setup` in a directory without - *acceptance*: Running `fiona-assistant setup` in a directory without
`fiona-settings.json` `fiona-settings.json`
creates one with defaults creates one with defaults
#### 4.11.2. Contrast with `fiona-assistant init` #### 4.14.2. Contrast with `fiona-assistant init`
> Status: Planned > Status: Planned
Clarify the difference between `init` and `setup` commands. Clarify the difference between `init` and `setup` commands.
- *4.11.2.1.* `NOT_IMPLEMENTED` `fiona-assistant init [directory]`: Initializes an llm-wiki - *4.14.2.1.* `NOT_IMPLEMENTED` `fiona-assistant init [directory]`: Initializes an llm-wiki
directory with directory with
default settings applied automatically without user interaction (see default settings applied automatically without user interaction (see
[3.1.1](#311-wiki-init)) [3.1.1](#311-wiki-init))
- *acceptance*: Documentation clearly distinguishes the two commands and - *acceptance*: Documentation clearly distinguishes the two commands and
their use cases their use cases
- *4.11.2.2.* `NOT_IMPLEMENTED` `fiona-assistant setup`: Runs interactive review of all possible - *4.14.2.2.* `NOT_IMPLEMENTED` `fiona-assistant setup`: Runs interactive review of all possible
settings, settings,
allowing user to customize each setting before applying allowing user to customize each setting before applying
- *acceptance*: `init` remains non-interactive and applies all defaults - *acceptance*: `init` remains non-interactive and applies all defaults
automatically automatically
- *4.11.2.3.* `NOT_IMPLEMENTED` `init` is designed for quick bootstrap with sensible defaults - *4.14.2.3.* `NOT_IMPLEMENTED` `init` is designed for quick bootstrap with sensible defaults
- *acceptance*: `setup` provides full interactive review of all configurable - *acceptance*: `setup` provides full interactive review of all configurable
settings settings
- *4.11.2.4.* `NOT_IMPLEMENTED` `setup` is designed for users who want to review and customize - *4.14.2.4.* `NOT_IMPLEMENTED` `setup` is designed for users who want to review and customize
settings settings
before initialization or update existing settings before initialization or update existing settings
- *acceptance*: `setup` can be run on an existing wiki to modify settings - *acceptance*: `setup` can be run on an existing wiki to modify settings
- *4.11.2.5.* `NOT_IMPLEMENTED` `init` creates the wiki structure; `setup` configures settings in - *4.14.2.5.* `NOT_IMPLEMENTED` `init` creates the wiki structure; `setup` configures settings in
an an
existing wiki existing wiki
- *4.11.2.6.* `NOT_IMPLEMENTED` Both commands respect the wiki root discovery mechanism - *4.14.2.6.* `NOT_IMPLEMENTED` Both commands respect the wiki root discovery mechanism
[4.9.1](#491-failure-reporting) [4.11.1](#4111-wiki-root-discovery-fiona-settingsjson)
--- ---
@@ -1983,12 +2017,16 @@ resolve against the current working directory; dropping
`file_log_location` disables file logging; an unopenable location `file_log_location` disables file logging; an unopenable location
logs a warning and keeps console logging. logs a warning and keeps console logging.
- *5.1.1.* `NOT_IMPLEMENTED` Standard `logging` module (or agreed equivalent); no new hard - *5.1.1.* The standard `logging` module is the diagnostics channel,
dependency. configured by `fiona.logging_config.setup_logging()`. No new hard
- *acceptance*: No direct `print` calls in `src/` production modules. dependency.
- *5.1.2.* `NOT_IMPLEMENTED` CLI-facing output stays stdout; diagnostics go to stderr with levels. - *acceptance*: CLI entry points call `setup_logging()`.
- *acceptance*: Tool output consumed by tests/scripts is unchanged. - *5.1.2.* `NOT_IMPLEMENTED` Error and warning diagnostics go to stderr
- *5.1.3.* `NOT_IMPLEMENTED` Existing AI-friendly output format is preserved for consumers. through the logging module. CLI-facing reports stay stdout prints.
- *acceptance*: Production modules do not `print` errors. Reports
may still print.
- *5.1.3.* Existing AI-friendly report format is preserved for consumers.
- *acceptance*: Tool output consumed by tests and scripts is unchanged.
--- ---
@@ -2010,7 +2048,9 @@ only READMEs.
`python_ruff/`, `run_tests.py`, `run_sanity.py`, `python_ruff/`, `run_tests.py`, `run_sanity.py`,
`settings_dev.json`). `settings_dev.json`).
- *acceptance*: All markdown documentation passes `mdoctor chklint`. - *acceptance*: All markdown documentation passes `mdoctor chklint`.
- *5.2.3.* `NOT_IMPLEMENTED` Link `SPEC.md` from `README.md` related documentation. - *5.2.3.* The root `README.md` links this spec under related
documentation.
- *acceptance*: `README.md` contains a markdown link to `SPEC.md`.
--- ---
@@ -2043,36 +2083,37 @@ and every
## 7. Priority Order ## 7. Priority Order
| Priority | Feature | Section | | Priority | Feature | Section | Status |
| -------- | ------- | ------- | | -------- | ------- | ------- | ------ |
| P1 | `wiki update` / `wiki check-update` | 3.1.2 | | P1 | `wiki update` / `wiki check-update` | 3.1.2 | Implemented |
| P1 | Git wrapper (`save`/`snapshot`/`restore`/`clean`/`undo`) | 3.2 | | P1 | Git wrapper (`save`/`snapshot`/`restore`/`clean`/`undo`/`status`) | 3.2 | Implemented |
| P1 | `wiki sanity` incl. dead-link check | 3.1.3 | | P1 | `wiki sanity` incl. dead-link check | 3.1.3 | Implemented |
| P2 | Frontmatter linter (fmlint) | 4.2 | | P1 | `wiki graph` | 3.1.4 | Implemented |
| P2 | Shellcheck library | 4.4 | | P2 | Frontmatter linter (fmlint) | 4.2 | Implemented |
| P2 | MD code block linting | 4.5 | | P2 | JSON linter (json-lint) | 4.13 | Implemented |
| P2 | JSON linter (json-lint) | 4.10 | | P2 | MDoctor auto-fix (`mdoctor fix`) | 4.1.1 | Implemented |
| P2 | HTML/JS linter (html-js-lint) | 4.12 | | P2 | Lint configuration (`fiona-settings.json`) | 4.1.2 | Implemented |
| P2 | Logging library | 5.1 | | P2 | Sanity runner failure reporting | 4.9.1 | Implemented |
| P3 | Frontmatter tags (`date`, `confidence`, `contested`) | 4.8.1 | | P2 | Shellcheck library | 4.6 | Planned |
| P3 | Backup script | 3.2.1 | | P2 | MD code block linting | 4.7 | Planned |
| P3 | Documentation | 5.2 | | P2 | HTML/JS linter (html-js-lint) | 4.12 | Planned |
| P4 | Non-MD file tracking (py/bash) | 4.6.1 | | P2 | Logging library | 5.1 | Partial |
| P4 | Project clarification | 5.3 | | P2 | Wiki root discovery via `fiona-settings.json` | 4.11.1 | Planned |
| P2 | MDoctor auto-fix (`mdoctor fix`) | 4.1.1 | | P2 | Settings manager (`fiona-assistant setup`) | 4.14 | Planned |
| P2 | Lint configuration (`fiona-settings.json`) | 4.1.2 | | P3 | Frontmatter tags (`date`, `confidence`, `contested`) | 4.10.3 | Planned |
| P2 | Sanity runner failure reporting | 4.7.1 | | P3 | Backup script | 3.2.1 | Planned |
| P2 | Wiki root discovery via `fiona-settings.json` | 4.9.1 | | P3 | Documentation | 5.2 | Partial |
| P2 | Settings manager (`fiona-assistant setup`) | 4.11 | | P4 | Non-MD file tracking (py/bash) | 4.8.1 | Planned |
| P4 | Project clarification | 5.3 | Planned |
--- ---
## 8. Open Questions ## 8. Open Questions
- Tagging format for python files and bash scripts [4.6](#46-shellcheck-library) - Tagging format for python files and bash scripts [4.8.1](#481-non-md-file-support)
is undecided. is undecided.
- Git wrapper location: implemented at `src/gittool/git_tool.py`. - Git wrapper location: implemented at `src/gittool/git_tool.py`.
- Wiki root discovery [4.9.1](#491-failure-reporting) - Wiki root discovery [4.11.1](#4111-wiki-root-discovery-fiona-settingsjson)
: which `fiona-settings.json` wins when : which `fiona-settings.json` wins when
several subdirectories contain one, and should ancestor directories be several subdirectories contain one, and should ancestor directories be
searched as a fallback before falling back to the current directory? searched as a fallback before falling back to the current directory?
+3
View File
@@ -5,6 +5,9 @@
# This script MUST be sourced to properly set up the environment: # This script MUST be sourced to properly set up the environment:
# source bootstrap # source bootstrap
# #
# Windows (PowerShell): dot-source bootstrap.ps1 instead
# . .\bootstrap.ps1 [--env name] [--python 3.x.x] [-c|--clean]
#
# What it does: # What it does:
# 1. Installs pyenv and required system dependencies if needed # 1. Installs pyenv and required system dependencies if needed
# 2. Initializes pyenv and pyenv-virtualenv in the current shell # 2. Initializes pyenv and pyenv-virtualenv in the current shell
+282
View File
@@ -0,0 +1,282 @@
# Generated by CURSOR: 2026-09-29 - Windows PowerShell bootstrap for Fiona development
#
# Project bootstrap for Windows. Dot-source it so the virtual environment
# stays active in the current session (same idea as `source bootstrap`):
#
# Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass
# . .\bootstrap.ps1
# . .\bootstrap.ps1 --env fiona_env
# . .\bootstrap.ps1 --env fiona_env --python 3.13.8 -c
#
# Creates a repo-local venv at .venvs\<name> with the Python launcher (py)
# or python on PATH. Does not install pyenv. --pyenv is accepted so the
# Linux flag still parses; on Windows it is a no-op notice.
#Requires -Version 5.1
# CURSOR: flags are parsed by hand. Windows PowerShell 5.1 does not bind
# `--python` to a parameter alias, and the bash script uses those flags.
function Write-FionaStatus {
param([string]$Message)
Write-Host "[+] $Message" -ForegroundColor Green
}
function Write-FionaWarning {
param([string]$Message)
Write-Host "[!] $Message" -ForegroundColor Yellow
}
function Write-FionaError {
param([string]$Message)
Write-Host "[x] $Message" -ForegroundColor Red
}
function Remove-FionaBootstrapFunctions {
if (Get-Variable -Name FionaPrevErrorAction -Scope 1 -ErrorAction SilentlyContinue) {
Set-Variable -Name ErrorActionPreference -Value $FionaPrevErrorAction -Scope 1
Remove-Variable -Name FionaPrevErrorAction -Scope 1 -ErrorAction SilentlyContinue
}
foreach ($name in @(
"Write-FionaStatus",
"Write-FionaWarning",
"Write-FionaError",
"Resolve-FionaPython",
"Remove-FionaBootstrapFunctions"
)) {
Remove-Item -Path "Function:\$name" -ErrorAction SilentlyContinue
}
}
function Resolve-FionaPython {
# CURSOR: pick a real interpreter. Prefer the py launcher so a requested
# version (3.13.8, then 3.13) wins over whatever `python` happens to be.
param([string]$Version)
$tags = @()
if ($Version) {
$tags += $Version
if ($Version -match '^(\d+\.\d+)') {
$minor = $Matches[1]
if ($minor -ne $Version) {
$tags += $minor
}
}
}
$py = Get-Command py -ErrorAction SilentlyContinue
if ($py) {
foreach ($tag in $tags) {
$exe = & py "-$tag" -c "import sys; print(sys.executable)" 2>$null
if ($LASTEXITCODE -eq 0 -and $exe) {
return @($exe)[-1].ToString().Trim()
}
}
if (-not $Version) {
$exe = & py -3 -c "import sys; print(sys.executable)" 2>$null
if ($LASTEXITCODE -eq 0 -and $exe) {
return @($exe)[-1].ToString().Trim()
}
}
}
if (-not $Version) {
foreach ($name in @("python", "python3")) {
$cmd = Get-Command $name -ErrorAction SilentlyContinue
if ($cmd -and $cmd.Source -notmatch "WindowsApps") {
return $cmd.Source
}
}
}
return $null
}
$FionaPrevErrorAction = $ErrorActionPreference
$ErrorActionPreference = "Stop"
# CURSOR: a failed pip/py call must be checked via $LASTEXITCODE, not thrown.
if (Get-Variable -Name PSNativeCommandUseErrorActionPreference -ErrorAction SilentlyContinue) {
$PSNativeCommandUseErrorActionPreference = $false
}
$Clean = $false
$EnvName = "test_env"
$PythonVersion = ""
$Pyenv = $false
$bootstrapArgs = @($args)
for ($i = 0; $i -lt $bootstrapArgs.Count; $i++) {
$token = [string]$bootstrapArgs[$i]
if ($token -eq "--pyenv") {
$Pyenv = $true
}
elseif ($token -eq "-c" -or $token -eq "--clean") {
$Clean = $true
}
elseif ($token -eq "--env") {
if (($i + 1) -ge $bootstrapArgs.Count) {
Write-FionaError "--env requires an environment name argument"
Remove-FionaBootstrapFunctions
return
}
$i++
$EnvName = [string]$bootstrapArgs[$i]
}
elseif ($token -eq "--python") {
if (($i + 1) -ge $bootstrapArgs.Count) {
Write-FionaError "--python requires a version number argument"
Remove-FionaBootstrapFunctions
return
}
$i++
$PythonVersion = [string]$bootstrapArgs[$i]
}
else {
Write-FionaError "Unknown option: $token"
Write-FionaError "Usage: . .\bootstrap.ps1 [--pyenv] [-c|--clean] [--env custom_name] [--python 3.x.x]"
Remove-FionaBootstrapFunctions
return
}
}
if ($MyInvocation.InvocationName -ne ".") {
Write-FionaError "Dot-source this script so the virtual environment stays active in this session."
Write-FionaError " . .\bootstrap.ps1"
Remove-FionaBootstrapFunctions
return
}
if ($Pyenv) {
Write-FionaWarning "Windows bootstrap uses a local venv under .venvs\. It does not install pyenv."
}
$repoRoot = $PSScriptRoot
if (-not $repoRoot) {
$repoRoot = (Get-Location).Path
}
Write-FionaStatus "Starting project bootstrap with environment: $EnvName"
try {
Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass -Force -ErrorAction Stop | Out-Null
}
catch {
# CURSOR: a GPO can refuse the process override. RemoteSigned still runs local scripts.
}
$pythonExe = Resolve-FionaPython -Version $PythonVersion
if (-not $pythonExe) {
Write-FionaError "Python is not installed, or version '$PythonVersion' is not available to the py launcher."
Write-FionaError "Install Python from https://www.python.org/downloads/ and enable the py launcher."
if ($PythonVersion) {
Write-FionaError "Then re-run: . .\bootstrap.ps1 --python $PythonVersion"
}
Remove-FionaBootstrapFunctions
return
}
$venvRoot = Join-Path $repoRoot ".venvs"
$venvPath = Join-Path $venvRoot $EnvName
if ($Clean -and (Test-Path -LiteralPath $venvPath)) {
Write-FionaStatus "Deleting existing virtual environment $EnvName..."
try {
Remove-Item -LiteralPath $venvPath -Recurse -Force
}
catch {
Write-FionaError "Failed to delete virtual environment $EnvName"
Write-FionaError $_.Exception.Message
Remove-FionaBootstrapFunctions
return
}
}
$activate = Join-Path $venvPath "Scripts\Activate.ps1"
if (-not (Test-Path -LiteralPath $activate)) {
Write-FionaStatus "Creating virtual environment $EnvName with $pythonExe..."
New-Item -ItemType Directory -Path $venvRoot -Force | Out-Null
& $pythonExe -m venv $venvPath
if ($LASTEXITCODE -ne 0) {
Write-FionaError "Failed to create virtual environment $EnvName"
Remove-FionaBootstrapFunctions
return
}
}
else {
Write-FionaStatus "Virtual environment $EnvName already exists"
}
Write-FionaStatus "Activating $EnvName..."
. $activate
if (-not $env:VIRTUAL_ENV) {
Write-FionaError "Failed to activate $EnvName"
Remove-FionaBootstrapFunctions
return
}
if ($env:PYTEST_ADDOPTS) {
$sanitized = $env:PYTEST_ADDOPTS -replace '--no-summary', '' -replace '(^|\s)-S(\s|$)', ' '
$sanitized = ($sanitized -replace '\s+', ' ').Trim()
if ($sanitized -ne $env:PYTEST_ADDOPTS.Trim()) {
Write-FionaWarning "Removing --no-summary from PYTEST_ADDOPTS so test output can be parsed"
if ($sanitized) {
$env:PYTEST_ADDOPTS = $sanitized
}
else {
Remove-Item Env:PYTEST_ADDOPTS
}
}
}
if ($env:FORCE_COLOR) {
Write-FionaWarning "Unsetting FORCE_COLOR so pytest output can be parsed"
Remove-Item Env:FORCE_COLOR
}
if ($env:PY_COLORS) {
Write-FionaWarning "Unsetting PY_COLORS so pytest output can be parsed"
Remove-Item Env:PY_COLORS
}
$pyproject = Join-Path $repoRoot "pyproject.toml"
if (-not (Test-Path -LiteralPath $pyproject)) {
Write-FionaError "No pyproject.toml found at $pyproject"
Remove-FionaBootstrapFunctions
return
}
Write-FionaStatus "Upgrading pip..."
& python -m pip install --upgrade pip
if ($LASTEXITCODE -ne 0) {
Write-FionaWarning "Failed to upgrade pip. Continuing with package installation..."
}
Write-FionaStatus "Installing package and dependencies from pyproject.toml..."
Push-Location $repoRoot
try {
& python -m pip install -e ".[dev]"
if ($LASTEXITCODE -ne 0) {
Write-FionaError "Failed to install package and dependencies from pyproject.toml"
Remove-FionaBootstrapFunctions
return
}
}
finally {
Pop-Location
}
$pythonCmd = Get-Command python -ErrorAction SilentlyContinue
$pythonWhere = if ($pythonCmd) { $pythonCmd.Source } else { "python" }
$pythonVersionText = (& python --version 2>&1 | Out-String).Trim()
$pipVersionText = (& python -m pip --version 2>&1 | Out-String).Trim()
Write-FionaStatus "Bootstrap completed successfully!"
Write-FionaStatus "Virtual environment '$EnvName' is active"
Write-FionaStatus "Python: $pythonVersionText ($pythonWhere)"
Write-FionaStatus "Pip: $pipVersionText"
Write-FionaStatus ""
Write-FionaStatus "To verify installation, try:"
Write-FionaStatus " python src/run_tests.py"
Write-FionaStatus " fiona-assistant --help"
Write-FionaStatus ""
Write-FionaStatus "Happy coding!"
Remove-FionaBootstrapFunctions
+12 -2
View File
@@ -20,7 +20,9 @@ The Fiona Assistant project provides command-line tools for:
cd fiona-assistant cd fiona-assistant
``` ```
2. Set up the Python environment using the bootstrap script: 2. Set up the Python environment using the bootstrap script.
Linux / macOS:
```bash ```bash
source bootstrap --env fiona_env source bootstrap --env fiona_env
@@ -32,6 +34,13 @@ The Fiona Assistant project provides command-line tools for:
source bootstrap --env fiona_env --python 3.11.0 source bootstrap --env fiona_env --python 3.11.0
``` ```
Windows (PowerShell):
```powershell
Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass
. .\bootstrap.ps1 --env fiona_env --python 3.11.0
```
3. Install the package in development mode: 3. Install the package in development mode:
```bash ```bash
@@ -87,7 +96,8 @@ pytest --cov=src
The project includes several development utilities: The project includes several development utilities:
- `bootstrap`: Set up the Python development environment - `bootstrap`: Set up the Python development environment (bash)
- `bootstrap.ps1`: Set up the Python development environment (PowerShell)
- `src/utils.sh`: Shell utility functions - `src/utils.sh`: Shell utility functions
- `src/install_packages.sh`: Install local Python packages - `src/install_packages.sh`: Install local Python packages
- `src/run_tests.sh`: Run the test suite - `src/run_tests.sh`: Run the test suite
+4
View File
@@ -0,0 +1,4 @@
"""Shellcheck package.
Wraps the external shellcheck linter for the Fiona-Assistant CLI.
"""
+382
View File
@@ -0,0 +1,382 @@
from __future__ import annotations
import argparse
import json
import logging
import pathlib
import shutil
import subprocess
import sys
from typing import Any, ClassVar
from customlinter.base import BaseLinter, LintViolation
from fiona.logging_config import setup_logging
logger = logging.getLogger(__name__)
class Shellcheck(BaseLinter):
"""Shellcheck linter that extends BaseLinter.
Wraps the external shellcheck binary to lint shell scripts,
providing AI-friendly aggregated violation reports following the
same pattern as python_ruff.
"""
# File extensions to scan
file_extensions: ClassVar[list[str]] = [".sh", ".bash", ".zsh", ".dash"]
# Settings key path in fiona-settings.json
settings_key_path: ClassVar[list[str]] = ["shellcheck"]
# Human-readable linter name for report headers
linter_name: ClassVar[str] = "Shellcheck"
# Violation codes - shellcheck rules, populated from output
VIOLATION_CODES: ClassVar[dict[str, dict[str, Any]]] = {}
def __init__(self, settings_file: pathlib.Path | None = None) -> None:
"""Initialize the Shellcheck linter."""
super().__init__(settings_file=settings_file)
def _find_shellcheck_bin(self) -> str:
"""Find the shellcheck binary on the system.
Returns:
Path to the shellcheck binary.
Raises:
RuntimeError: If shellcheck is not found on the system.
"""
# First try to find shellcheck in PATH
shellcheck_bin = shutil.which("shellcheck")
# If not found in PATH, check if shellcheck-py installed it in the current Python environment
if shellcheck_bin is None:
# Try to find it in the Python environment's bin directory
python_bin = pathlib.Path(sys.executable).parent
env_shellcheck = python_bin / "shellcheck"
if env_shellcheck.exists():
shellcheck_bin = str(env_shellcheck)
if shellcheck_bin is None:
# Provide clear install hint
install_hint = (
"shellcheck is not installed or not found in PATH.\n"
"\n"
"To install shellcheck:\n"
"\n"
"With pip (recommended):\n"
" pip install shellcheck-py\n"
"\n"
"On Ubuntu/Debian:\n"
" sudo apt-get install shellcheck\n"
"\n"
"On macOS (with Homebrew):\n"
" brew install shellcheck\n"
"\n"
"On Fedora/RHEL:\n"
" sudo dnf install shellcheck\n"
"\n"
"On Arch Linux:\n"
" sudo pacman -S shellcheck\n"
"\n"
"Or download from: https://www.shellcheck.net/"
)
logger.error(install_hint)
raise RuntimeError(install_hint)
return shellcheck_bin
def lint(self, target_path: str | pathlib.Path, fix: bool = False) -> list[dict]:
"""Lint shell scripts using shellcheck.
Args:
target_path: Path to the file or directory to lint.
fix: Not supported for shellcheck (always False).
Returns:
List of violation dictionaries with file, line, column, code, and message.
Raises:
RuntimeError: If shellcheck is not installed.
"""
resolved_path = pathlib.Path(target_path).resolve()
try:
shellcheck_bin = self._find_shellcheck_bin()
except RuntimeError as e:
# Return a special violation indicating shellcheck is missing
return [{
"file": str(resolved_path),
"line": 0,
"column": 0,
"code": "SHELLCHECK_NOT_FOUND",
"message": str(e),
"severity": "error"
}]
args = [shellcheck_bin, "--format=json", str(resolved_path)]
result = subprocess.run(args, capture_output=True, text=True, check=False)
stdout = result.stdout.strip()
if stdout:
try:
parsed = json.loads(stdout)
# shellcheck returns a list of violations
if isinstance(parsed, list):
return parsed
return []
except json.JSONDecodeError:
# If JSON parsing fails, return empty list
logger.warning("Failed to parse shellcheck output as JSON")
return []
return []
def lint_file(self, filepath: pathlib.Path | str) -> list[LintViolation]:
"""Lint a single shell script file using shellcheck.
Args:
filepath: Path to the shell script file to lint.
Returns:
List of LintViolation objects.
"""
resolved_filepath = pathlib.Path(filepath).resolve()
# Check if file should be skipped
if self._should_skip(resolved_filepath):
return []
try:
shellcheck_bin = self._find_shellcheck_bin()
except RuntimeError as e:
# Return a special violation indicating shellcheck is missing
return [LintViolation(
filepath=resolved_filepath,
line=0,
column=0,
code="SHELLCHECK_NOT_FOUND",
message=str(e).split('\n')[0], # First line only for message
rule_id="SHELLCHECK_NOT_FOUND",
severity="error"
)]
args = [shellcheck_bin, "--format=json", str(resolved_filepath)]
result = subprocess.run(args, capture_output=True, text=True, check=False)
stdout = result.stdout.strip()
if not stdout:
return []
violations = []
try:
parsed = json.loads(stdout)
if not isinstance(parsed, list):
return []
except json.JSONDecodeError:
logger.warning("Failed to parse shellcheck output as JSON for %s", filepath)
return []
for violation in parsed:
# shellcheck JSON format includes:
# - file: the file path
# - line: line number
# - column: column number
# - level: severity (error, warning, info, style)
# - code: the rule code (e.g., SC1009, SC2086)
# - message: the violation message
code = violation.get("code", "UNKNOWN")
message = violation.get("message", "")
level = violation.get("level", "error")
# Store rule info in VIOLATION_CODES
if code not in self.VIOLATION_CODES:
self.VIOLATION_CODES[code] = {
"rule_name": code,
"description": message
}
# Map shellcheck severity levels to our severity
severity_map = {
"error": "error",
"warning": "warning",
"info": "info",
"style": "info"
}
severity = severity_map.get(level, "error")
# Create LintViolation
lint_violation = LintViolation(
filepath=resolved_filepath,
line=violation.get("line", 0),
column=violation.get("column", 0),
code=code,
message=f"{violation.get('line', 0)}:{violation.get('column', 0)} {code} {message}",
rule_id=code,
severity=severity
)
violations.append(lint_violation)
return violations
def compress_violations(
self, violations: list[dict] | str, target: str | pathlib.Path | None = None
) -> dict:
"""Compress violations using the shared BaseLinter format.
For backward compatibility, this method can accept:
- Raw shellcheck JSON output (list of dicts or JSON string)
- Already converted LintViolation objects
Args:
violations: List of violation dicts from shellcheck or JSON string.
target: Target directory path.
Returns:
Dictionary with compressed violations in shared format.
"""
# Handle cases where raw JSON string was passed instead of parsed list
if isinstance(violations, str):
violations = json.loads(violations) if violations.strip() else []
# Check if violations are already LintViolation objects or raw dicts
if violations and isinstance(violations[0], LintViolation):
# Already converted, use directly
lint_violations = violations
else:
# Convert raw shellcheck violations to LintViolation objects
lint_violations = []
for violation in violations:
# Handle the special case for missing shellcheck
if violation.get("code") == "SHELLCHECK_NOT_FOUND":
code = "SHELLCHECK_NOT_FOUND"
message = violation.get("message", "")
if code not in self.VIOLATION_CODES:
self.VIOLATION_CODES[code] = {
"rule_name": code,
"description": "shellcheck binary not found on system"
}
filepath = pathlib.Path(violation.get("file", "."))
lint_violation = LintViolation(
filepath=filepath,
line=violation.get("line", 0),
column=violation.get("column", 0),
code=code,
message=message,
rule_id=code,
severity="error"
)
lint_violations.append(lint_violation)
continue
# Normal shellcheck violation
code = violation.get("code", "UNKNOWN")
message = violation.get("message", "")
if code not in self.VIOLATION_CODES:
self.VIOLATION_CODES[code] = {
"rule_name": code,
"description": message
}
# Get filepath
try:
filepath = pathlib.Path(violation["file"]).resolve()
except KeyError:
if target is None:
filepath = pathlib.Path.cwd()
else:
filepath = pathlib.Path(target).resolve()
lint_violation = LintViolation(
filepath=filepath,
line=violation.get("line", 0),
column=violation.get("column", 0),
code=code,
message=f"{violation.get('line', 0)}:{violation.get('column', 0)} {code}",
rule_id=code,
severity="error"
)
lint_violations.append(lint_violation)
# Use the base class compress_violations method
return super().compress_violations(lint_violations, target)
def format_violations(
self, violations: list[dict] | dict | str, target: str | pathlib.Path | None = None, target_path: str | pathlib.Path | None = None
) -> str:
"""Format violations using the shared BaseLinter format.
Args:
violations: Violations to format (can be compressed dict, raw violations, or JSON string).
target: Target directory path (for backward compatibility).
target_path: Target directory path (alternative parameter name for backward compatibility).
Returns:
Formatted string with violation report.
"""
# Handle backward compatibility: use target_path if target is None
if target_path is not None and target is None:
target = target_path
# Reuse compressed dict if already compressed, otherwise compress
if isinstance(violations, dict):
compressed = violations
else:
compressed = self.compress_violations(violations, target)
# Use the base class format_compressed_violations method
return self.format_compressed_violations(compressed)
def check_shellcheck(self, target_dir: str):
"""Check shell scripts in a directory using shellcheck.
Args:
target_dir: Path to the directory to check.
Returns:
Formatted violation report string.
"""
raw_json = self.lint(target_dir)
compressed_violations = self.compress_violations(raw_json, target_dir)
return self.format_violations(compressed_violations, target_dir)
def main():
"""Command-line interface for the shellcheck tool."""
parser = argparse.ArgumentParser(
description="shellcheck - Lint shell scripts"
)
subparsers = parser.add_subparsers(dest="subcommand", help="Available subcommands")
# chklint subcommand
chklint_parser = subparsers.add_parser("chklint", help="Check shell scripts for violations")
chklint_parser.add_argument(
"directory",
nargs="?",
default=".",
help="Directory to lint (default: current directory)"
)
args = parser.parse_args()
setup_logging()
shellcheck = Shellcheck()
if args.subcommand is None:
# Default to chklint with current directory
args.subcommand = "chklint"
args.directory = "."
if args.subcommand == "chklint":
violations = shellcheck.check_shellcheck(args.directory)
print(violations)
if __name__ == "__main__":
main()
+476
View File
@@ -0,0 +1,476 @@
"""Tests for Shellcheck module."""
import json
import os
import pathlib
import tempfile
from unittest.mock import MagicMock, patch
import pytest
from shellcheck.shellcheck import Shellcheck, main
@pytest.fixture
def shellcheck_linter():
"""Fixture that provides a Shellcheck instance."""
return Shellcheck()
class TestShellcheck:
"""Tests for Shellcheck class."""
def test_lint_file_with_violation(self, shellcheck_linter, tmp_path):
"""Test lint_file detects a known shellcheck violation."""
test_file = tmp_path / "test.sh"
test_file.write_text("#!/bin/bash\nfor file in $1; do echo $file; done\n")
mock_violation = {
"file": str(test_file),
"line": 2,
"column": 15,
"level": "warning",
"code": "SC2086",
"message": "Double quote to prevent globbing and word splitting."
}
with patch(
'shellcheck.shellcheck.shutil.which',
return_value='/usr/bin/shellcheck'
) as _, patch(
'shellcheck.shellcheck.subprocess.run'
) as mock_run:
mock_run.return_value = MagicMock(
returncode=0,
stdout=json.dumps([mock_violation]),
stderr=""
)
violations = shellcheck_linter.lint_file(str(test_file))
assert len(violations) == 1
assert violations[0].code == "SC2086"
assert violations[0].line == 2
assert violations[0].column == 15
assert violations[0].severity == "warning"
assert "SC2086" in violations[0].message
def test_lint_clean_file(self, shellcheck_linter, tmp_path):
"""Test lint_file returns empty list for clean file."""
clean_file = tmp_path / "clean.sh"
clean_file.write_text("#!/bin/bash\necho 'Hello World'\n")
with patch(
'shellcheck.shellcheck.shutil.which',
return_value='/usr/bin/shellcheck'
) as _, patch(
'shellcheck.shellcheck.subprocess.run'
) as mock_run:
mock_run.return_value = MagicMock(
returncode=0,
stdout="[]",
stderr=""
)
violations = shellcheck_linter.lint_file(str(clean_file))
assert isinstance(violations, list)
assert len(violations) == 0
def test_compress_violations(self, shellcheck_linter):
"""Test compress_violations method."""
violations = [
{
"file": "/path/to/script.sh",
"line": 1,
"column": 10,
"code": "SC2086",
"message": "Double quote to prevent globbing.",
"level": "warning"
},
{
"file": "/path/to/script.sh",
"line": 2,
"column": 15,
"code": "SC2086",
"message": "Double quote to prevent globbing."
}
]
target = pathlib.Path("/path/to")
result = shellcheck_linter.compress_violations(violations, target)
assert isinstance(result, dict)
assert "files" in result
assert "script.sh" in result["files"]
assert len(result["files"]["script.sh"]) == 2
def test_compress_violations_with_string(self, shellcheck_linter):
"""Test compress_violations with string input."""
violations_json = '[{"file": "/path/to/script.sh", "line": 1, "column": 10, "code": "SC2086", "message": "test", "level": "warning"}]'
target = pathlib.Path("/path/to")
result = shellcheck_linter.compress_violations(violations_json, target)
assert isinstance(result, dict)
assert "files" in result
assert "script.sh" in result["files"]
def test_format_violations(self, shellcheck_linter):
"""Test format_violations method."""
compressed = {
"files": {
"script.sh": ["1:10 SC2086"]
},
"descriptions": {
"SC2086": {"rule_name": "SC2086", "description": "Double quote"}
},
"meta": {"file_count": 1, "total_violations": 1, "target": "/path/to"}
}
result = shellcheck_linter.format_violations(compressed, target="/path/to")
assert isinstance(result, str)
assert "Shellcheck Violations" in result
assert "SC2086" in result
assert "SUMMARY:" in result
def test_format_violations_empty(self, shellcheck_linter):
"""Test format_violations with empty input."""
compressed = {
"files": {},
"descriptions": {},
"meta": {"file_count": 0, "total_violations": 0}
}
result = shellcheck_linter.format_violations(compressed, target="/path/to")
assert "Shellcheck Violations" in result
assert "No violations found" in result
def test_check_shellcheck(self, shellcheck_linter, tmp_path):
"""Test check_shellcheck method."""
test_file = tmp_path / "test.sh"
test_file.write_text("#!/bin/bash\necho 'Hello'\n")
with patch(
'shellcheck.shellcheck.shutil.which',
return_value='/usr/bin/shellcheck'
) as _, patch(
'shellcheck.shellcheck.subprocess.run'
) as mock_run:
mock_run.return_value = MagicMock(
returncode=0,
stdout="[]",
stderr=""
)
result = shellcheck_linter.check_shellcheck(str(tmp_path))
assert isinstance(result, str)
assert "Shellcheck Violations" in result
class TestShellcheckMain:
"""Tests for shellcheck.main() function."""
def test_main_default(self, capsys):
"""Test main() with default arguments."""
with tempfile.TemporaryDirectory() as temp_dir:
test_file = os.path.join(temp_dir, "test.sh")
with open(test_file, 'w') as f:
f.write("#!/bin/bash\necho 'world'\n")
with patch(
'sys.argv', ['shellcheck']
), patch(
'shellcheck.shellcheck.shutil.which',
return_value='/usr/bin/shellcheck'
) as _, patch(
'shellcheck.shellcheck.subprocess.run'
) as mock_run:
mock_run.return_value = MagicMock(
returncode=0,
stdout="[]",
stderr=""
)
main()
captured = capsys.readouterr()
assert "Shellcheck Violations" in captured.out
def test_main_with_directory(self, capsys):
"""Test main() with directory argument."""
with tempfile.TemporaryDirectory() as temp_dir:
test_file = os.path.join(temp_dir, "test.sh")
with open(test_file, 'w') as f:
f.write("#!/bin/bash\necho 'world'\n")
with patch(
'sys.argv', ['shellcheck', 'chklint', temp_dir]
), patch(
'shellcheck.shellcheck.shutil.which',
return_value='/usr/bin/shellcheck'
) as _, patch(
'shellcheck.shellcheck.subprocess.run'
) as mock_run:
mock_run.return_value = MagicMock(
returncode=0,
stdout="[]",
stderr=""
)
main()
captured = capsys.readouterr()
assert "Shellcheck Violations" in captured.out
class TestShellcheckBinaryNotFound:
"""Tests for shellcheck binary not found scenario."""
def test_find_shellcheck_bin_raises_error(self, shellcheck_linter):
"""Test _find_shellcheck_bin raises RuntimeError when shellcheck not found."""
with patch(
'shellcheck.shellcheck.shutil.which',
return_value=None
) as _, patch.object(
pathlib.Path, 'exists', return_value=False
):
with pytest.raises(RuntimeError) as exc_info:
shellcheck_linter._find_shellcheck_bin()
error_msg = str(exc_info.value)
assert "shellcheck is not installed" in error_msg
assert "pip install shellcheck-py" in error_msg
def test_lint_returns_error_when_binary_missing(self, shellcheck_linter, tmp_path):
"""Test lint returns SHELLCHECK_NOT_FOUND violation when binary is missing."""
test_file = tmp_path / "test.sh"
test_file.write_text("#!/bin/bash\necho 'test'\n")
with patch(
'shellcheck.shellcheck.shutil.which',
return_value=None
) as _, patch.object(
pathlib.Path, 'exists', return_value=False
):
violations = shellcheck_linter.lint(str(test_file))
assert len(violations) == 1
assert violations[0]["code"] == "SHELLCHECK_NOT_FOUND"
assert "shellcheck is not installed" in violations[0]["message"]
def test_lint_file_returns_error_when_binary_missing(self, shellcheck_linter, tmp_path):
"""Test lint_file returns SHELLCHECK_NOT_FOUND violation when binary is missing."""
test_file = tmp_path / "test.sh"
test_file.write_text("#!/bin/bash\necho 'test'\n")
with patch(
'shellcheck.shellcheck.shutil.which',
return_value=None
) as _, patch.object(
pathlib.Path, 'exists', return_value=False
):
violations = shellcheck_linter.lint_file(str(test_file))
assert len(violations) == 1
assert violations[0].code == "SHELLCHECK_NOT_FOUND"
assert "shellcheck is not installed" in violations[0].message
def test_missing_binary_produces_clear_message(self, tmp_path):
"""Test that missing binary produces a clear install-hint message."""
test_file = tmp_path / "test.sh"
test_file.write_text("#!/bin/bash\necho 'test'\n")
shellcheck_linter = Shellcheck()
with patch(
'shellcheck.shellcheck.shutil.which',
return_value=None
) as _, patch.object(
pathlib.Path, 'exists', return_value=False
):
violations = shellcheck_linter.lint_file(str(test_file))
compressed = shellcheck_linter.compress_violations(violations, str(tmp_path))
formatted = shellcheck_linter.format_compressed_violations(compressed)
assert "SHELLCHECK_NOT_FOUND" in formatted
assert "shellcheck is not installed" in formatted
assert "not installed" in formatted.lower()
assert "Traceback" not in formatted
class TestShellcheckEdgeCases:
"""Tests for Shellcheck edge branches."""
def test_lint_with_empty_output(self, shellcheck_linter):
"""Test lint returns [] when shellcheck emits empty output."""
with patch(
'shellcheck.shellcheck.shutil.which',
return_value='/usr/bin/shellcheck'
) as _, patch(
'shellcheck.shellcheck.subprocess.run'
) as mock_run:
mock_run.return_value = MagicMock(
returncode=0, stdout="", stderr=""
)
assert shellcheck_linter.lint("src") == []
def test_lint_with_non_list_json(self, shellcheck_linter):
"""Test lint returns [] when shellcheck emits a non-list JSON payload."""
with patch(
'shellcheck.shellcheck.shutil.which',
return_value='/usr/bin/shellcheck'
) as _, patch(
'shellcheck.shellcheck.subprocess.run'
) as mock_run:
mock_run.return_value = MagicMock(
returncode=0, stdout='{"violations": []}', stderr=""
)
assert shellcheck_linter.lint("src") == []
def test_lint_with_invalid_json(self, shellcheck_linter):
"""Test lint returns [] when shellcheck output is not valid JSON."""
with patch(
'shellcheck.shellcheck.shutil.which',
return_value='/usr/bin/shellcheck'
) as _, patch(
'shellcheck.shellcheck.subprocess.run'
) as mock_run:
mock_run.return_value = MagicMock(
returncode=0, stdout='not valid json', stderr=""
)
assert shellcheck_linter.lint("src") == []
def test_compress_violations_with_missing_file_key(self, shellcheck_linter):
"""Test compress_violations handles violations without file key."""
violations = [{
"line": 1,
"column": 10,
"code": "SC1000",
"message": "test"
}]
with patch.object(pathlib.Path, 'cwd', return_value=pathlib.Path("/mock/cwd")):
compressed = shellcheck_linter.compress_violations(violations, "/mock/target")
assert "files" in compressed
def test_severity_mapping(self, shellcheck_linter, tmp_path):
"""Test that shellcheck severity levels are mapped correctly."""
test_file = tmp_path / "test.sh"
for level, expected_severity in [("error", "error"), ("warning", "warning"), ("info", "info"), ("style", "info")]:
with patch(
'shellcheck.shellcheck.shutil.which',
return_value='/usr/bin/shellcheck'
) as _, patch(
'shellcheck.shellcheck.subprocess.run'
) as mock_run:
mock_violation = {
"file": str(test_file),
"line": 1,
"column": 1,
"code": "SC0001",
"message": "test",
"level": level
}
mock_run.return_value = MagicMock(
returncode=0,
stdout=json.dumps([mock_violation]),
stderr=""
)
violations = shellcheck_linter.lint_file(str(test_file))
assert violations[0].severity == expected_severity
def test_file_extensions(self, shellcheck_linter):
"""Test that shellcheck recognizes the correct file extensions."""
assert ".sh" in shellcheck_linter.file_extensions
assert ".bash" in shellcheck_linter.file_extensions
assert ".zsh" in shellcheck_linter.file_extensions
assert ".dash" in shellcheck_linter.file_extensions
def test_linter_name(self, shellcheck_linter):
"""Test that the linter name is Shellcheck."""
assert shellcheck_linter.linter_name == "Shellcheck"
def test_lint_shellcheck_not_found(self, shellcheck_linter, tmp_path):
"""Test lint returns SHELLCHECK_NOT_FOUND when binary not found."""
test_file = tmp_path / "test.sh"
test_file.write_text("#!/bin/bash\necho test\n")
with patch(
'shellcheck.shellcheck.shutil.which',
return_value=None
) as _, patch.object(
pathlib.Path, 'exists', return_value=False
):
violations = shellcheck_linter.lint(str(test_file))
assert len(violations) == 1
assert violations[0]["code"] == "SHELLCHECK_NOT_FOUND"
def test_lint_empty_stdout(self, shellcheck_linter, tmp_path):
"""Test lint returns [] when stdout is empty."""
test_file = tmp_path / "test.sh"
test_file.write_text("#!/bin/bash\necho test\n")
with patch(
'shellcheck.shellcheck.shutil.which',
return_value='/usr/bin/shellcheck'
) as _, patch(
'shellcheck.shellcheck.subprocess.run'
) as mock_run:
mock_run.return_value = MagicMock(
returncode=0,
stdout="",
stderr=""
)
violations = shellcheck_linter.lint(str(test_file))
assert violations == []
def test_lint_json_decode_error(self, shellcheck_linter, tmp_path):
"""Test lint handles JSON decode errors."""
test_file = tmp_path / "test.sh"
test_file.write_text("#!/bin/bash\necho test\n")
with patch(
'shellcheck.shellcheck.shutil.which',
return_value='/usr/bin/shellcheck'
) as _, patch(
'shellcheck.shellcheck.subprocess.run'
) as mock_run:
mock_run.return_value = MagicMock(
returncode=0,
stdout='not valid json',
stderr=""
)
violations = shellcheck_linter.lint(str(test_file))
assert violations == []
def test_format_violations_with_target_path(self, shellcheck_linter):
"""Test format_violations with target_path parameter."""
compressed = {
"files": {"test.sh": ["1:1 SC2086"]},
"descriptions": {"SC2086": {"rule_name": "SC2086", "description": "test"}},
"meta": {"file_count": 1, "total_violations": 1}
}
result = shellcheck_linter.format_violations(
compressed, target_path="/some/path"
)
assert isinstance(result, str)
assert "Shellcheck Violations" in result
def test_lint_file_skips_readonly_zones(self, shellcheck_linter, tmp_path):
"""Test lint_file skips files in read-only zones."""
# Create a file in a read-only zone directory
readonly_dir = tmp_path / "personal"
readonly_dir.mkdir()
readonly_file = readonly_dir / "test.sh"
readonly_file.write_text("#!/bin/bash\necho test\n")
violations = shellcheck_linter.lint_file(str(readonly_file))
# Should return empty because it's in a read-only zone
assert violations == []
+215 -36
View File
@@ -18,11 +18,14 @@ Ordered by priority. Each item references its section in [SPEC.md](./SPEC.md)
- [x] `version` tag support - [x] `version` tag support
- [x] `fiona-assistant wiki init` — copy packaged template into a target - [x] `fiona-assistant wiki init` — copy packaged template into a target
directory (basic flow; hardening tracked under P1) directory (basic flow; hardening tracked under P1)
- [x] Windows PowerShell bootstrap (`bootstrap.ps1`): repo-local venv under
`.venvs\<name>`, same flags as the bash `bootstrap`
## P0 — Packaging and Structure Fixes ## P0 — Packaging and Structure Fixes
From the 2026-09-23 structure audit. These are repo-hygiene items that From the 2026-09-23 structure audit, plus the 2026-09-29 layout audit
block a correct install or make the docs contradict the code. below. These are repo-hygiene items that block a correct install or make
the docs contradict the code.
- [x] Fix PyPI packaging so a non-editable install works (wheel build - [x] Fix PyPI packaging so a non-editable install works (wheel build
confirmed `python_ruff` is missing entirely) confirmed `python_ruff` is missing entirely)
@@ -75,6 +78,177 @@ block a correct install or make the docs contradict the code.
- [x] pytests should show which test are failing, - [x] pytests should show which test are failing,
- [x] markdownlint should show which files are in violation , what line - [x] markdownlint should show which files are in violation , what line
- [x] same thing for ruff - [x] same thing for ruff
- [ ] Remove the phantom `html_js_lint` package and `html-js-lint` console
script from `pyproject.toml` until SPEC 4.12 is implemented. The
directory `src/html_js_lint/` does not exist. Detail is item 2 in
the 2026-09-29 audit below
### 2026-09-29 structure audit
`pyproject.toml` declares a PEP 621 project and the code lives under
`src/`, but the tree is nine sibling import packages plus loose scripts.
A src layout is meant to install one import package. Target shape when
this cluster is done:
```text
src/fiona/
├── __main__.py
├── librarian/
├── mdoctor/
├── customlinter/
├── python_ruff/
├── gittool/
├── sanity_runner/
├── wiki/
└── data/llm_wiki/ # templates, no fake package
tests/ # repo root, not installed
```
Keep a single required entry point:
`fiona-assistant = fiona.__main__:main`. Optional thin scripts can stay
as extra entry points that call into those submodules. Do this as one
change set: import paths, tests, entry points, and docs move together.
Half-moving a package leaves both layouts on `sys.path`.
- [ ] Collapse the nine top-level packages into `fiona` subpackages
- [ ] Current install names, from `packages.find` `include` and from
`src/fiona_assistant.egg-info/top_level.txt`: `customlinter`,
`fiona`, `gittool`, `librarian`, `llm-wiki`, `mdoctor`,
`python_ruff`, `sanity_runner`, `wiki`
- [ ] `fiona/__main__.py` imports them as top-level modules
(`from librarian.librarian import main`, `from wiki.wiki import
wiki_init`, and the same for `customlinter`, `gittool`,
`mdoctor`, `python_ruff`)
- [ ] Same-name module pattern to preserve while moving:
`librarian/librarian.py`, `mdoctor/mdoctor.py`,
`python_ruff/python_ruff.py`, `sanity_runner/sanity_runner.py`.
`gittool` is the odd one: the module is `git_tool.py`
- [ ] `wiki` is a generic top-level name and will collide with any
other installed project that also ships a `wiki` package
- [ ] After the move, `packages.find` `include` should list `fiona`
only. An allow-list is how `python_ruff` was shipped late and
how `html_js_lint` stayed declared after the directory vanished
- [ ] Remove the phantom `html_js_lint` declaration (same checkbox as
the item above this section)
- [ ] `[project.scripts]` maps `html-js-lint` to
`html_js_lint.html_js_lint:main`
- [ ] `packages.find` `include` lists `html_js_lint`
- [ ] `src/fiona_assistant.egg-info/entry_points.txt` still has that
script from the last editable install
- [ ] `src/html_js_lint/` does not exist. Invoking `html-js-lint`
fails at import. SPEC 4.12 is the future feature; the entry
point should not ship until that directory exists
- [ ] `html5validator` is in runtime `dependencies` and is not
imported anywhere under `src/`. Drop it with the phantom
script, or keep it only when SPEC 4.12 lands
- [ ] Delete `src/__init__.py`
- [ ] The file's only content is the comment `# Fiona tools package`
- [ ] An `__init__.py` in `src/` makes `src` itself a package whenever
the repo root is on `sys.path`. The src layout exists so
packages are importable only after install
- [ ] That is why bytecode for `run_sanity.py` and `run_tests.py`
lands in `src/__pycache__/` (`run_sanity.cpython-313.pyc`,
`run_tests.cpython-313.pyc`, `__init__.cpython-313.pyc`)
- [ ] Stop tests from editing `sys.path`
- [ ] `src/tests/conftest.py` does
`sys.path.insert(0, os.path.dirname(os.path.dirname(...)))`,
which puts `src/` on the path, then imports `librarian`,
`mdoctor`, `python_ruff`, and `wiki` as top-level names
- [ ] `src/tests/__init__.py` exists, so `tests` is a package sitting
inside the source root. Standard layout is a repo-root `tests/`
directory that is not installed
- [ ] `[tool.pytest.ini_options]` sets `testpaths = ["src/tests"]` and
has no `pythonpath`. Coverage `source = ["src"]` treats the
mixed script-and-package directory as the measured tree
- [ ] Replacement: `pip install -e .` in the dev env, or
`pythonpath = ["src"]` once there is a single `fiona` package.
The path edit hides "package not installed" failures
- [ ] The 2026-09-27 conftest consolidation (outer `src/conftest.py`
removed) stays valid. This item replaces the remaining
`sys.path` bootstrap, it does not undo that merge
- [ ] Decide where the loose `src/` files live
- [ ] `src/run_sanity.py` and `src/run_tests.py` are modules, not
packages. They are absent from `packages.find`, so a wheel
does not install them. They are how this repo runs its own
sanity and tests (`python src/run_sanity.py`)
- [ ] `src/install_packages.sh`, `src/utils.sh`, and
`src/settings_dev.json` sit in the same directory. Dev config
and shell helpers are not package source
- [ ] Either give `run_sanity` / `run_tests` real entry points under
`fiona`, or move them to a repo-root `scripts/` (or `tools/`)
directory that is not on the package path
- [ ] Replace the hyphenated `llm-wiki` package with package data
- [ ] `import llm-wiki` is a `SyntaxError`. `src/llm-wiki/__init__.py`
exists only so setuptools detects the directory. The
`pyproject.toml` comment already documents that hack
- [ ] `[tool.setuptools.package-data]` maps `"llm-wiki" = ["*", "**/*"]`
- [ ] `src/llm-wiki/__init__.py` sets `__version__ = "0.1.0"` while
`[project]` `version` is `0.36.0`. Two versions for one
distribution
- [ ] Move the template tree to something importable, for example
`src/fiona/data/llm_wiki/`, and load files with
`importlib.resources`. Update `wiki init` / `wiki update`
path helpers (`get_llm_wiki_source_path`) in the same change
- [ ] Root `README.md` links `./llm-wiki/AGENTS.md`. The file is
`src/llm-wiki/AGENTS.md`
- [ ] Get setuptools metadata out of `src/`
- [ ] `src/fiona_assistant.egg-info/` holds `PKG-INFO`,
`entry_points.txt`, `requires.txt`, `SOURCES.txt`,
`top_level.txt`. That is install metadata. It belongs at the
repo root (or nowhere, if it is only a local editable-install
artifact)
- [ ] `.gitignore` already ignores `*.egg-info/`, so this directory
should not be committed, but `where = ["src"]` can still see it
during package discovery
- [ ] The egg name `fiona_assistant` is the setuptools normalization
of project name `fiona-assistant`. Leave the normalization
alone; only the directory location is wrong
- [ ] Keep a single coverage config, and point it at the code that exists
- [ ] Both `.coveragerc` and `[tool.coverage]` in `pyproject.toml`
exist. Coverage reads `.coveragerc` first, so the pyproject
block is unused
- [ ] `.coveragerc` still omits `src/mdoctor/fmlint.py` and
`src/python_ruff/pycustomlint.py`. Those modules live under
`src/customlinter/` (`fmlint.py`, `pycustomlint.py`)
- [ ] Both files share the same `exclude_lines` list. After deleting
`.coveragerc`, confirm `pytest --cov` still honors the
pyproject `source`, `omit`, and `exclude_lines`
- [ ] `coverage.xml` at the repo root is a generated report. It is
not matched by `.gitignore` (`*.log` and `.coverage` are;
`coverage.xml` is not)
- [ ] Raise the setuptools build pin so `[project]` is valid
- [ ] `[build-system]` `requires` is `setuptools>=42`
- [ ] The `[project]` table (PEP 621) needs setuptools 61 or newer.
An older setuptools that satisfies `>=42` can fail the build
- [ ] Set `requires = ["setuptools>=61"]` (or a current floor) and
rebuild the wheel
- [ ] Sort runtime dependencies from repo-only tools
- [ ] `ruff` is imported by `src/python_ruff/python_ruff.py`, so it
stays in `dependencies`
- [ ] `pylint` is in `dependencies` with no version pin, and nothing
under `src/` imports it. Move it to the `dev` extra or drop it
- [ ] There is no `[tool.ruff]` table and no `ruff.toml`. If this
repo is linted with Ruff, the rule set belongs in
`pyproject.toml`
- [ ] `requires-python` is `>=3.8`. Local bytecode in
`src/__pycache__/` is CPython 3.13. Classifiers only say
`Programming Language :: Python :: 3`. The bootstrap examples
use 3.11. Record the versions this repo actually runs, and
confirm syntax such as `str | None` is either covered by
`from __future__ import annotations` or by a higher
`requires-python`
- [ ] Make the structure docs match the tree (also listed under P3)
- [ ] `src/README.md` "Project Structure" lists only `fiona/`,
`librarian/`, `mdoctor/`, `tests/`, and `README.md`. Missing
from that diagram: `customlinter/`, `python_ruff/`, `gittool/`,
`sanity_runner/`, `wiki/`, `llm-wiki/`, `run_sanity.py`,
`run_tests.py`, `settings_dev.json`, `utils.sh`,
`install_packages.sh`
- [ ] MDoctor's description in that file is still
`[Description to be added]`, and Contributing is still
`[Contribution guidelines to be added]`
- [ ] Refresh this diagram again after the package collapse, so the
docs describe `src/fiona/` rather than today's sibling packages
## P1 — Wiki Lifecycle and Version Control ## P1 — Wiki Lifecycle and Version Control
@@ -115,11 +289,12 @@ block a correct install or make the docs contradict the code.
WAITING lines, assigned via a carriage-return constant); wiki WAITING lines, assigned via a carriage-return constant); wiki
sanity output unchanged sanity output unchanged
- [x] Frontmatter linter (fmlint) (SPEC 4.2) - [x] Frontmatter linter (fmlint) (SPEC 4.2)
- [x] Implement `src/mdoctor/fmlint.py` module - [x] Implement `src/customlinter/fmlint.py`
- [x] Write TDD tests for fmlint - [x] Write TDD tests for fmlint
- [x] Add CLI integration: `fiona-assistant fmlint chklint [directory]` - [x] Add CLI integration: `fiona-assistant fmlint chklint [directory]`
- [x] Integrate into `run_sanity.py` - [x] Integrate into `run_sanity.py` and `wiki sanity`
- [x] Add settings support via `fiona-settings.json` - [x] Add settings support via `fiona-settings.json`
- [x] SKILL.md name, folder, and description checks (FML004-FML006)
- [x] Generalize compress and format violations for all linters - [x] Generalize compress and format violations for all linters
(SPEC 4.3.1, 4.9.3) (SPEC 4.3.1, 4.9.3)
- [x] `BaseLinter` provides `compress_violations()` and - [x] `BaseLinter` provides `compress_violations()` and
@@ -133,23 +308,25 @@ block a correct install or make the docs contradict the code.
`dict[rel_path, list[dict]]`) onto the shared base format `dict[rel_path, list[dict]]`) onto the shared base format
- [x] Keep all linter reports diffable: same sections, same order - [x] Keep all linter reports diffable: same sections, same order
(update SPEC 4.1/4.5 and tests together) (update SPEC 4.1/4.5 and tests together)
- [ ] JSON linter (json-lint) (SPEC 4.10) - [x] JSON linter (json-lint) (SPEC 4.13)
- [ ] Implement `src/json_lint/json_lint.py` module - [x] Implement `src/customlinter/jsonlint.py`
- [ ] Write TDD tests for json-lint - [x] Write TDD tests for json-lint
- [ ] JSON syntax validation using standard `json` module - [x] JSON syntax validation using the standard `json` module
- [ ] JSON style rules (indentation, trailing commas, key ordering) - [x] JSON style rules (indentation, trailing commas, key ordering)
- [ ] Add CLI integration: `fiona-assistant json-lint chklint [directory]` - [x] CLI: `fiona-assistant json-lint chklint` and `fix`
- [ ] Support `--fix` flag for auto-fixing certain violations - [x] Settings via the `json` section of `fiona-settings.json`
- [ ] Add settings support via `fiona-settings.json` (json section) - [x] Integrated into `run_sanity.py` and `wiki sanity`
- [ ] Integrate into `run_sanity.py` - [ ] Shellcheck library (SPEC 4.6)
- [ ] Shellcheck library (SPEC 4.4)
- [ ] add shellcheck to toml - [ ] add shellcheck to toml
- [ ] Wrap shellcheck like `python_ruff` (AI-friendly violation report) - [ ] Wrap shellcheck like `python_ruff` (AI-friendly violation report)
- [ ] Clear install-hint error when shellcheck is missing - [ ] Clear install-hint error when shellcheck is missing
- [ ] Lint fenced code blocks inside MD files (SPEC 4.5) - [ ] Lint fenced code blocks inside MD files (SPEC 4.7)
- [ ] Python blocks via Ruff, shell blocks via shellcheck - [ ] Python blocks via Ruff, shell blocks via shellcheck
- [ ] Logging library instead of `print` across the codebase (SPEC 5.1) - [ ] Logging library instead of `print` for diagnostics (SPEC 5.1)
- [ ] Diagnostics to stderr with levels; preserve tool output format - [x] Shared `fiona.logging_config.setup_logging()` on CLI entry points
- [ ] Error and warning diagnostics go to stderr through logging.
CLI reports stay stdout prints. `git_tool`, `graph_generator`,
and several CLIs still `print` errors
- [x] Clear existing lint violations (SPEC 1 constraint: Ruff and - [x] Clear existing lint violations (SPEC 1 constraint: Ruff and
PyMarkdown must pass) PyMarkdown must pass)
- [x] Ruff: 0 violations — removed unused imports and unnecessary - [x] Ruff: 0 violations — removed unused imports and unnecessary
@@ -161,10 +338,7 @@ block a correct install or make the docs contradict the code.
`front-matter` extension (files with frontmatter no longer raise `front-matter` extension (files with frontmatter no longer raise
phantom MD003/MD022/MD041) and ignores the frontmatter `title` phantom MD003/MD022/MD041) and ignores the frontmatter `title`
for MD025 for MD025
- [ ] Make a framework, so that when `fiona-assistant` is called - [ ] Settings manager, `fiona-assistant setup` (SPEC 4.14)
`fiona-settings.json` is read and all tools can see it
(SPEC 4.9.1)
- [ ] it signifies that is the root of the llm-wiki
- [x] When running sanity, make sure that markdownlint tests also include - [x] When running sanity, make sure that markdownlint tests also include
outer dir of the src/ because there are markdown files there outer dir of the src/ because there are markdown files there
- [x] in `run_sanity.py`, show the failing test function and assert ex. - [x] in `run_sanity.py`, show the failing test function and assert ex.
@@ -232,11 +406,11 @@ WARNING run_tests: pytest short summary missing from output; failure details com
environment in `_sanitize_pytest_env` (pytest skips summary environment in `_sanitize_pytest_env` (pytest skips summary
trimming when `CI` is set); keep junit parsing as the safety net trimming when `CI` is set); keep junit parsing as the safety net
- [ ] in toc generator settings, add a per file rule, (TBD: put in spec) - [x] in toc generator settings, per-file glob overrides in the `file`
- [ ] when a rule matches a file, it will follow the defined settings in the dictionari section (SPEC 4.10.2)
- [ ] instead of current directory as default, find a fiona-settings.json - [ ] instead of current directory as default, find a fiona-settings.json
in the current directory / subdirectory, that will be the llm-wiki in the current directory / subdirectory, that will be the llm-wiki
root and default directory for commands (SPEC 4.9.1) root and default directory for commands (SPEC 4.11.1)
- [ ] Enable the pymarkdown `markdown-tables` extension in - [ ] Enable the pymarkdown `markdown-tables` extension in
`fiona-settings.json` so table rules (MD055/MD056/MD058) run in `fiona-settings.json` so table rules (MD055/MD056/MD058) run in
`run_sanity.py` (SPEC 4.1.2 known limitation) `run_sanity.py` (SPEC 4.1.2 known limitation)
@@ -249,25 +423,28 @@ WARNING run_tests: pytest short summary missing from output; failure details com
- [ ] Backup script for llm-wiki so users can recover if something goes - [ ] Backup script for llm-wiki so users can recover if something goes
wrong (SPEC 3.2.1) wrong (SPEC 3.2.1)
- [ ] Frontmatter tags on MD files (SPEC 4.8.1) - [ ] Frontmatter tags on MD files (SPEC 4.10.3)
- [x] `version` - [x] `version`
- [ ] `date` tag - [ ] `date` tag
- [ ] Quality signal: `confidence` - [ ] Quality signal: `confidence`
- [ ] `contested` flag (true if claims are disputed) - [ ] `contested` flag (true if claims are disputed)
- [ ] Project documentation (SPEC 5.2) - [ ] Project documentation (SPEC 5.2)
- [ ] Write `src/README.md` with project description - [x] Root `README.md` links `SPEC.md`
- [ ] Setup instructions (`pip install -e .`) - [x] Root README and `AGENTS.md` document `bootstrap` and `bootstrap.ps1`
- [ ] Usage examples for librarian and mdoctor - [ ] Refresh `librarian/README.md` and `mdoctor/README.md` for the
- [ ] Update `librarian/README.md` with actual usage info current subcommands (`list`, `toc`, `chklint`, `fix`)
- [ ] Add `mdoctor/README.md` - [ ] Refresh `src/README.md` structure (`wiki/`, `python_ruff/`,
`run_tests.py`, `run_sanity.py`, `settings_dev.json`). Full
gap list is the last item of the P0 2026-09-29 structure audit,
including the root README link to `./llm-wiki/AGENTS.md`
- [ ] Process hygiene: use semantic commit prefixes - [ ] Process hygiene: use semantic commit prefixes
(`feat:`, `fix:`, `docs:`, ...) per project agent rule 8.1 (`feat:`, `fix:`, `docs:`, ...) per project agent rule 8.1
- [ ] `fiona-assistant wiki graph` make a class that can generate the obsidian style - [x] `fiona-assistant wiki graph` (SPEC 3.1.4): link parser, graph,
graph/link for md files association in html format (SPEC 3.1.4.) HTML template, and CLI in `src/wiki/graph_generator.py`
## P4 — Design Decisions Needed ## P4 — Design Decisions Needed
- [ ] Librarian: version tracking for non-MD files (SPEC 4.6.1) - [ ] Librarian: version tracking for non-MD files (SPEC 4.8.1)
- [ ] Python files — format TBD - [ ] Python files — format TBD
- [ ] Bash scripts — format TBD - [ ] Bash scripts — format TBD
- [ ] Decide the tagging format before implementing - [ ] Decide the tagging format before implementing
@@ -282,6 +459,8 @@ WARNING run_tests: pytest short summary missing from output; failure details com
## Open Questions (SPEC) ## Open Questions (SPEC)
- Tagging format for python files and bash scripts (SPEC 4.6.1) - Tagging format for python files and bash scripts (SPEC 4.8.1)
- Git wrapper location: `src/vcs/` vs `src/librarian/vcs.py` (SPEC 3.2) - Git wrapper location: implemented at `src/gittool/git_tool.py` (SPEC 3.2)
- make a class for generating html graph for md linkages like obsidian - Wiki root discovery (SPEC 4.11.1): the nearest `fiona-settings.json`
wins; error when two at the same depth are equally near. Ancestor
search is still open.