Compare commits
4 Commits
a3d35c7f12
...
shellcheck
| Author | SHA1 | Date | |
|---|---|---|---|
| 579f37f112 | |||
| e0ad912eb4 | |||
| a745ba92c1 | |||
| c8b98dbbd6 |
@@ -5,6 +5,7 @@ __pycache__/
|
||||
|
||||
# Virtual environments
|
||||
.venv/
|
||||
.venvs/
|
||||
venv/
|
||||
env/
|
||||
ENV/
|
||||
|
||||
@@ -1,10 +1,10 @@
|
||||
---
|
||||
name: Fiona-Assistant Agent Rules
|
||||
version: 1.3.1
|
||||
version: 1.3.2
|
||||
title: LLM Agent Rules
|
||||
type: summary
|
||||
created: 2025-09-23
|
||||
updated: 2026-09-26
|
||||
updated: 2026-09-29
|
||||
tags: [agents, rules, guidelines, llm, ai]
|
||||
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
|
||||
|
||||
> 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
|
||||
# Bare minimum - always run this first
|
||||
@@ -106,6 +108,17 @@ source bootstrap --env <env_name> --python <version>
|
||||
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,
|
||||
installs dependencies, and ensures a consistent development environment.
|
||||
All testing and development MUST happen within this environment.
|
||||
@@ -177,7 +190,8 @@ fiona-assistant/
|
||||
│ └── install_packages.sh # Dependency installer
|
||||
│
|
||||
├── 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
|
||||
```
|
||||
|
||||
@@ -302,6 +316,12 @@ git commit -m "test: add TDD tests for name/version extraction"
|
||||
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)
|
||||
- Python tasks: Load `python-tdd` skill
|
||||
- Wiki tasks: Load `llm-wiki` skill
|
||||
@@ -435,7 +455,7 @@ These rules **CAN** be overridden by:
|
||||
| Task | Required Action |
|
||||
| ---- | -------------- |
|
||||
| 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 |
|
||||
| Modifying code | Write tests first (TDD) |
|
||||
| Before commit | Run tests + linters |
|
||||
|
||||
@@ -81,12 +81,22 @@ python -m pip install fiona-assistant
|
||||
```
|
||||
|
||||
- **Create and activate the virtual environment:**
|
||||
|
||||
```bash
|
||||
|
||||
Linux / macOS:
|
||||
|
||||
```bash
|
||||
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
|
||||
│
|
||||
├── pyproject.toml # Project configuration
|
||||
├── bootstrap # Environment setup script
|
||||
├── bootstrap # Environment setup script (bash)
|
||||
├── bootstrap.ps1 # Environment setup script (PowerShell)
|
||||
├── LICENSE # GPL-3.0-only
|
||||
└── README.md # This file
|
||||
```
|
||||
|
||||
@@ -1,9 +1,9 @@
|
||||
---
|
||||
name: Fiona-Assistant Specification
|
||||
version: 0.38.0
|
||||
version: 0.39.0
|
||||
title: Project Spec Sheet
|
||||
created: 2026-09-23
|
||||
updated: 2026-09-28
|
||||
updated: 2026-09-29
|
||||
type: summary
|
||||
---
|
||||
|
||||
@@ -18,8 +18,10 @@ type: summary
|
||||
- [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.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.6. `fiona-assistant wiki [subcommand] [directory]`](#26-fiona-assistant-wiki-subcommand-directory)
|
||||
- [2.5. `fiona-assistant fmlint [subcommand] [directory]`](#25-fiona-assistant-fmlint-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.1. llm-wiki Lifecycle Management](#31-llm-wiki-lifecycle-management)
|
||||
- [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.6. Progress Display](#496-progress-display)
|
||||
- [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.3. MD Frontmatter Tagging](#4103-md-frontmatter-tagging)
|
||||
- [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.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.1. HTML Validation](#4121-html-validation)
|
||||
- [4.12.2. JavaScript Linting](#4122-javascript-linting)
|
||||
- [4.12.3. CLI Integration](#4123-cli-integration)
|
||||
- [4.12.4. Configuration](#4124-configuration)
|
||||
- [4.12.5. Sanity Integration](#4125-sanity-integration)
|
||||
- [4.11. settings_manager (Settings Management)](#411-settings_manager-settings-management)
|
||||
- [4.11.1. Interactive Setup (`fiona-assistant setup`)](#4111-interactive-setup-fiona-assistant-setup)
|
||||
- [4.11.2. Contrast with `fiona-assistant init`](#4112-contrast-with-fiona-assistant-init)
|
||||
- [4.13. json-lint (JSON Linter)](#413-json-lint-json-linter)
|
||||
- [4.13.1. JSON Syntax Validation](#4131-json-syntax-validation)
|
||||
- [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.1. Logging Library](#51-logging-library)
|
||||
- [5.2. Documentation (medium priority)](#52-documentation-medium-priority)
|
||||
@@ -160,10 +162,10 @@ reserve LLM tokens for creative and analytical work.
|
||||
## 2. Current Capabilities
|
||||
|
||||
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;
|
||||
the planned wiki root discovery [4.9.1](#491-failure-reporting)
|
||||
will replace that default with
|
||||
the planned wiki root discovery [4.11.1](#4111-wiki-root-discovery-fiona-settingsjson)
|
||||
will replace that default with
|
||||
the directory containing `fiona-settings.json`.
|
||||
|
||||
### 2.1. `fiona-assistant`
|
||||
@@ -199,14 +201,34 @@ the directory containing `fiona-settings.json`.
|
||||
- `chklint [directory]`: Lint Python sources with ruff and print an
|
||||
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.
|
||||
- `chklint [directory]`: Check HTML and JavaScript files for lint violations.
|
||||
Supports `--json` flag for AI-friendly output format.
|
||||
- `--fix`: Auto-fix certain violations where supported by underlying linters.
|
||||
- No subcommand: default to `chklint .`.
|
||||
- `chklint [directory]`: Validate markdown frontmatter
|
||||
([4.2](#42-frontmatter-linter-fmlint)). The report lists violations
|
||||
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.
|
||||
- `init [directory]`: Initialize the directory as an llm-wiki by copying
|
||||
@@ -242,10 +264,10 @@ Notes:
|
||||
|
||||
### 3.1. llm-wiki Lifecycle Management
|
||||
|
||||
> Status: Partially Implemented
|
||||
> Status: 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`
|
||||
|
||||
@@ -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),
|
||||
Python lint (`python-ruff`), the custom markdown linter
|
||||
(`mdlinter`, 4.3.3), and any other registered linters
|
||||
(shellcheck once 4.4 ships).
|
||||
(`mdlinter`, 4.3.3), JSON lint (`jsonlint`, 4.13), and any other
|
||||
registered linters (shellcheck once 4.6 ships).
|
||||
- *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
|
||||
to
|
||||
@@ -386,7 +408,7 @@ violation
|
||||
[4.2](#42-frontmatter-linter-fmlint)
|
||||
— required `name`/`version` frontmatter per
|
||||
[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)/
|
||||
[4.9.4](#494-run-timing): failing checks' linter reports first (clean runs
|
||||
print no report), a `Results:`
|
||||
@@ -399,16 +421,14 @@ violation
|
||||
|
||||
#### 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.
|
||||
>
|
||||
> Phase 1 (Core): Link parser + graph builder + basic HTML output + basic CLI
|
||||
> Phase 2 (CLI): Command integration with existing wiki subcommands
|
||||
> Phase 3 (Features): Color spectrum, edge coloring, gravity force, click handlers
|
||||
> Phase 4 (Polish): BFS layout + animated appearance + 360deg separation + clustering
|
||||
> Status: Implemented
|
||||
> Phases 1-4 are in that module and template: link parser, CLI,
|
||||
> color and physics, and the BFS layout.
|
||||
|
||||
Generate an interactive Obsidian-style graph visualization showing connections between
|
||||
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 |
|
||||
| `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 |
|
||||
| `status` | Print a short git status. Does not change the repository |
|
||||
|
||||
#### 3.2.1. Backup Script
|
||||
|
||||
@@ -785,7 +806,7 @@ ignored by MD025 |
|
||||
| `md060.enabled` | Implemented | False; table style rule diverges from Node.js
|
||||
|
|
||||
| `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
|
||||
per file in TOCs |
|
||||
| `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
|
||||
package is `src/llm-wiki/fiona-settings.json`; `wiki init` copies it
|
||||
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)
|
||||
|
||||
> Status: Planned
|
||||
> Status: Implemented
|
||||
>
|
||||
> Covers: `src/customlinter/fmlint.py`. A custom linter specifically for
|
||||
> 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
|
||||
|
||||
> Status: Planned
|
||||
> Status: Implemented
|
||||
|
||||
Validate that all markdown files in an llm-wiki directory have proper
|
||||
frontmatter with required fields.
|
||||
@@ -865,22 +886,22 @@ editing |
|
||||
| `sources` | No | Source file references (e.g. `raw/articles/source-name.md`) |
|
||||
| `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
|
||||
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
|
||||
[project agent rule 10.1](AGENTS.md#101-md-file-frontmatter)). All other
|
||||
fields, including `title`, are optional.
|
||||
- *acceptance*: A md file missing `version` field is reported with file path
|
||||
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
|
||||
.
|
||||
- *acceptance*: A md file with `name` and `version` but no `title` passes
|
||||
validation
|
||||
(`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
|
||||
line number (if known). Violation messages use the format `<code> -
|
||||
<message>`.
|
||||
@@ -888,62 +909,62 @@ validation
|
||||
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
|
||||
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).
|
||||
- *acceptance*: A md file with malformed YAML frontmatter is reported with
|
||||
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).
|
||||
- *acceptance*: Running on a directory with all valid frontmatter reports no
|
||||
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`
|
||||
[3.1.3](#313-wiki-sanity) and `run_sanity.py` [4.9](#49-test-and-sanity-runners).
|
||||
|
||||
#### 4.2.2. CLI Integration
|
||||
|
||||
> Status: Planned
|
||||
> Status: Implemented
|
||||
|
||||
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.
|
||||
- *acceptance*: Running `fiona-assistant fmlint` on a directory with invalid
|
||||
frontmatter
|
||||
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.
|
||||
- *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
|
||||
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
|
||||
|
||||
> Status: Planned
|
||||
> Status: Implemented
|
||||
|
||||
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']`).
|
||||
- *acceptance*: Changing required fields in `fiona-settings.json` changes
|
||||
validation
|
||||
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`
|
||||
maps file types to their specific required fields.
|
||||
- *acceptance*: Disabling the linter via settings skips frontmatter
|
||||
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).
|
||||
- *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`
|
||||
(e.g., `['FML002']` to ignore missing frontmatter).
|
||||
- *acceptance*: Files matching patterns in `ignore_file` are skipped during
|
||||
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`
|
||||
(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`
|
||||
> (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
|
||||
|
||||
@@ -1257,8 +1278,8 @@ the verdict
|
||||
> Status: Implemented
|
||||
>
|
||||
> Every linter check in the sanity runner (markdownlint, frontmatter_lint,
|
||||
> pycustomlint, mdlinter) prints the same AI-friendly report structure so the
|
||||
> reports are diffable across linters.
|
||||
> pycustomlint, mdlinter, jsonlint) prints the same AI-friendly report
|
||||
> structure so the reports are diffable across linters.
|
||||
|
||||
- *4.9.3.1.* The report starts with a `<Linter Name> Violations` header followed
|
||||
by `TARGET: <scanned path>`.
|
||||
@@ -1452,32 +1473,6 @@ section of
|
||||
- `--non-recursive` still forces direct files only regardless of
|
||||
`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`)
|
||||
|
||||
> Status: Implemented
|
||||
@@ -1576,6 +1571,30 @@ reports an
|
||||
A file without an H1 is skipped with `skipped ... (no H1 heading)`
|
||||
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)
|
||||
@@ -1586,15 +1605,17 @@ reports an
|
||||
> dispatches to the tool modules so every tool is reachable through one
|
||||
> command. Each tool also keeps its standalone CLI; `librarian` and
|
||||
> `mdoctor` are installed as console scripts, while `python-ruff` is
|
||||
> available only through `fiona-assistant`. All dispatch modules
|
||||
> (`fiona`, `python_ruff`) ship in the wheel.
|
||||
> available only through `fiona-assistant`. `fmlint`, `json-lint`, and
|
||||
> 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 | Behavior |
|
||||
| ------- | -------- |
|
||||
| `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 toc [directory]` | Generate a TOC
|
||||
[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) |
|
||||
| `fiona-assistant mdoctor [args]` | Delegate to the mdoctor CLI; defaults to
|
||||
`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;
|
||||
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
|
||||
[3.1.1](#311-wiki-init) |
|
||||
| `fiona-assistant wiki check-update [directory]` | Check for core-file updates
|
||||
@@ -1614,6 +1641,8 @@ defaults to `chklint .` |
|
||||
[3.1.2](#312-wiki-update) |
|
||||
| `fiona-assistant wiki sanity [directory]` | Run all sanity checks
|
||||
[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.
|
||||
- *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)
|
||||
|
||||
> 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
|
||||
> HTML syntax and structure, and JavaScript code quality. Uses existing Python
|
||||
> 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
|
||||
|
||||
Covers: `src/fiona/settings_manager.py`. Provides interactive and
|
||||
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
|
||||
|
||||
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
|
||||
- *acceptance*: Running `fiona-assistant setup` with no arguments starts the
|
||||
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
|
||||
- *acceptance*: User can navigate through all settings with Enter to accept
|
||||
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
|
||||
- *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
|
||||
accept all defaults without modification
|
||||
- *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.11.1.6.* `NOT_IMPLEMENTED` Support non-interactive mode via flags (e.g., `--yes`,
|
||||
- *4.14.1.5.* `NOT_IMPLEMENTED` Display current values for each setting before prompting
|
||||
- *4.14.1.6.* `NOT_IMPLEMENTED` Support non-interactive mode via flags (e.g., `--yes`,
|
||||
`--default`) for
|
||||
AI agents to run deterministically
|
||||
- *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
|
||||
- *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
|
||||
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
|
||||
`fiona-settings.json`
|
||||
creates one with defaults
|
||||
|
||||
#### 4.11.2. Contrast with `fiona-assistant init`
|
||||
#### 4.14.2. Contrast with `fiona-assistant init`
|
||||
|
||||
> Status: Planned
|
||||
|
||||
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
|
||||
default settings applied automatically without user interaction (see
|
||||
[3.1.1](#311-wiki-init))
|
||||
- *acceptance*: Documentation clearly distinguishes the two commands and
|
||||
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,
|
||||
allowing user to customize each setting before applying
|
||||
- *acceptance*: `init` remains non-interactive and applies all defaults
|
||||
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
|
||||
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
|
||||
before initialization or update existing 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
|
||||
existing wiki
|
||||
- *4.11.2.6.* `NOT_IMPLEMENTED` Both commands respect the wiki root discovery mechanism
|
||||
[4.9.1](#491-failure-reporting)
|
||||
- *4.14.2.6.* `NOT_IMPLEMENTED` Both commands respect the wiki root discovery mechanism
|
||||
[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
|
||||
logs a warning and keeps console logging.
|
||||
|
||||
- *5.1.1.* `NOT_IMPLEMENTED` Standard `logging` module (or agreed equivalent); no new hard
|
||||
dependency.
|
||||
- *acceptance*: No direct `print` calls in `src/` production modules.
|
||||
- *5.1.2.* `NOT_IMPLEMENTED` CLI-facing output stays stdout; diagnostics go to stderr with levels.
|
||||
- *acceptance*: Tool output consumed by tests/scripts is unchanged.
|
||||
- *5.1.3.* `NOT_IMPLEMENTED` Existing AI-friendly output format is preserved for consumers.
|
||||
- *5.1.1.* The standard `logging` module is the diagnostics channel,
|
||||
configured by `fiona.logging_config.setup_logging()`. No new hard
|
||||
dependency.
|
||||
- *acceptance*: CLI entry points call `setup_logging()`.
|
||||
- *5.1.2.* `NOT_IMPLEMENTED` Error and warning diagnostics go to stderr
|
||||
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`,
|
||||
`settings_dev.json`).
|
||||
- *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
|
||||
|
||||
| Priority | Feature | Section |
|
||||
| -------- | ------- | ------- |
|
||||
| P1 | `wiki update` / `wiki check-update` | 3.1.2 |
|
||||
| P1 | Git wrapper (`save`/`snapshot`/`restore`/`clean`/`undo`) | 3.2 |
|
||||
| P1 | `wiki sanity` incl. dead-link check | 3.1.3 |
|
||||
| P2 | Frontmatter linter (fmlint) | 4.2 |
|
||||
| P2 | Shellcheck library | 4.4 |
|
||||
| P2 | MD code block linting | 4.5 |
|
||||
| P2 | JSON linter (json-lint) | 4.10 |
|
||||
| P2 | HTML/JS linter (html-js-lint) | 4.12 |
|
||||
| P2 | Logging library | 5.1 |
|
||||
| P3 | Frontmatter tags (`date`, `confidence`, `contested`) | 4.8.1 |
|
||||
| P3 | Backup script | 3.2.1 |
|
||||
| P3 | Documentation | 5.2 |
|
||||
| P4 | Non-MD file tracking (py/bash) | 4.6.1 |
|
||||
| P4 | Project clarification | 5.3 |
|
||||
| P2 | MDoctor auto-fix (`mdoctor fix`) | 4.1.1 |
|
||||
| P2 | Lint configuration (`fiona-settings.json`) | 4.1.2 |
|
||||
| P2 | Sanity runner failure reporting | 4.7.1 |
|
||||
| P2 | Wiki root discovery via `fiona-settings.json` | 4.9.1 |
|
||||
| P2 | Settings manager (`fiona-assistant setup`) | 4.11 |
|
||||
| Priority | Feature | Section | Status |
|
||||
| -------- | ------- | ------- | ------ |
|
||||
| P1 | `wiki update` / `wiki check-update` | 3.1.2 | Implemented |
|
||||
| P1 | Git wrapper (`save`/`snapshot`/`restore`/`clean`/`undo`/`status`) | 3.2 | Implemented |
|
||||
| P1 | `wiki sanity` incl. dead-link check | 3.1.3 | Implemented |
|
||||
| P1 | `wiki graph` | 3.1.4 | Implemented |
|
||||
| P2 | Frontmatter linter (fmlint) | 4.2 | Implemented |
|
||||
| P2 | JSON linter (json-lint) | 4.13 | Implemented |
|
||||
| P2 | MDoctor auto-fix (`mdoctor fix`) | 4.1.1 | Implemented |
|
||||
| P2 | Lint configuration (`fiona-settings.json`) | 4.1.2 | Implemented |
|
||||
| P2 | Sanity runner failure reporting | 4.9.1 | Implemented |
|
||||
| P2 | Shellcheck library | 4.6 | Planned |
|
||||
| P2 | MD code block linting | 4.7 | Planned |
|
||||
| P2 | HTML/JS linter (html-js-lint) | 4.12 | Planned |
|
||||
| P2 | Logging library | 5.1 | Partial |
|
||||
| P2 | Wiki root discovery via `fiona-settings.json` | 4.11.1 | Planned |
|
||||
| P2 | Settings manager (`fiona-assistant setup`) | 4.14 | Planned |
|
||||
| P3 | Frontmatter tags (`date`, `confidence`, `contested`) | 4.10.3 | Planned |
|
||||
| P3 | Backup script | 3.2.1 | Planned |
|
||||
| P3 | Documentation | 5.2 | Partial |
|
||||
| P4 | Non-MD file tracking (py/bash) | 4.8.1 | Planned |
|
||||
| P4 | Project clarification | 5.3 | Planned |
|
||||
|
||||
---
|
||||
|
||||
## 8. Open Questions
|
||||
|
||||
- Tagging format for python files and bash scripts [4.6](#46-shellcheck-library)
|
||||
is undecided.
|
||||
- Tagging format for python files and bash scripts [4.8.1](#481-non-md-file-support)
|
||||
is undecided.
|
||||
- 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
|
||||
several subdirectories contain one, and should ancestor directories be
|
||||
searched as a fallback before falling back to the current directory?
|
||||
|
||||
@@ -5,6 +5,9 @@
|
||||
# This script MUST be sourced to properly set up the environment:
|
||||
# source bootstrap
|
||||
#
|
||||
# Windows (PowerShell): dot-source bootstrap.ps1 instead
|
||||
# . .\bootstrap.ps1 [--env name] [--python 3.x.x] [-c|--clean]
|
||||
#
|
||||
# What it does:
|
||||
# 1. Installs pyenv and required system dependencies if needed
|
||||
# 2. Initializes pyenv and pyenv-virtualenv in the current shell
|
||||
|
||||
+282
@@ -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
@@ -20,7 +20,9 @@ The Fiona Assistant project provides command-line tools for:
|
||||
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
|
||||
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
|
||||
```
|
||||
|
||||
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:
|
||||
|
||||
```bash
|
||||
@@ -87,7 +96,8 @@ pytest --cov=src
|
||||
|
||||
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/install_packages.sh`: Install local Python packages
|
||||
- `src/run_tests.sh`: Run the test suite
|
||||
|
||||
@@ -0,0 +1,4 @@
|
||||
"""Shellcheck package.
|
||||
|
||||
Wraps the external shellcheck linter for the Fiona-Assistant CLI.
|
||||
"""
|
||||
@@ -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()
|
||||
@@ -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 == []
|
||||
|
||||
@@ -18,11 +18,14 @@ Ordered by priority. Each item references its section in [SPEC.md](./SPEC.md)
|
||||
- [x] `version` tag support
|
||||
- [x] `fiona-assistant wiki init` — copy packaged template into a target
|
||||
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
|
||||
|
||||
From the 2026-09-23 structure audit. These are repo-hygiene items that
|
||||
block a correct install or make the docs contradict the code.
|
||||
From the 2026-09-23 structure audit, plus the 2026-09-29 layout audit
|
||||
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
|
||||
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] markdownlint should show which files are in violation , what line
|
||||
- [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
|
||||
|
||||
@@ -115,11 +289,12 @@ block a correct install or make the docs contradict the code.
|
||||
WAITING lines, assigned via a carriage-return constant); wiki
|
||||
sanity output unchanged
|
||||
- [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] 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] SKILL.md name, folder, and description checks (FML004-FML006)
|
||||
- [x] Generalize compress and format violations for all linters
|
||||
(SPEC 4.3.1, 4.9.3)
|
||||
- [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
|
||||
- [x] Keep all linter reports diffable: same sections, same order
|
||||
(update SPEC 4.1/4.5 and tests together)
|
||||
- [ ] JSON linter (json-lint) (SPEC 4.10)
|
||||
- [ ] Implement `src/json_lint/json_lint.py` module
|
||||
- [ ] Write TDD tests for json-lint
|
||||
- [ ] JSON syntax validation using standard `json` module
|
||||
- [ ] JSON style rules (indentation, trailing commas, key ordering)
|
||||
- [ ] Add CLI integration: `fiona-assistant json-lint chklint [directory]`
|
||||
- [ ] Support `--fix` flag for auto-fixing certain violations
|
||||
- [ ] Add settings support via `fiona-settings.json` (json section)
|
||||
- [ ] Integrate into `run_sanity.py`
|
||||
- [ ] Shellcheck library (SPEC 4.4)
|
||||
- [x] JSON linter (json-lint) (SPEC 4.13)
|
||||
- [x] Implement `src/customlinter/jsonlint.py`
|
||||
- [x] Write TDD tests for json-lint
|
||||
- [x] JSON syntax validation using the standard `json` module
|
||||
- [x] JSON style rules (indentation, trailing commas, key ordering)
|
||||
- [x] CLI: `fiona-assistant json-lint chklint` and `fix`
|
||||
- [x] Settings via the `json` section of `fiona-settings.json`
|
||||
- [x] Integrated into `run_sanity.py` and `wiki sanity`
|
||||
- [ ] Shellcheck library (SPEC 4.6)
|
||||
- [ ] add shellcheck to toml
|
||||
- [ ] Wrap shellcheck like `python_ruff` (AI-friendly violation report)
|
||||
- [ ] 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
|
||||
- [ ] Logging library instead of `print` across the codebase (SPEC 5.1)
|
||||
- [ ] Diagnostics to stderr with levels; preserve tool output format
|
||||
- [ ] Logging library instead of `print` for diagnostics (SPEC 5.1)
|
||||
- [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
|
||||
PyMarkdown must pass)
|
||||
- [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
|
||||
phantom MD003/MD022/MD041) and ignores the frontmatter `title`
|
||||
for MD025
|
||||
- [ ] Make a framework, so that when `fiona-assistant` is called
|
||||
`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
|
||||
- [ ] Settings manager, `fiona-assistant setup` (SPEC 4.14)
|
||||
- [x] When running sanity, make sure that markdownlint tests also include
|
||||
outer dir of the src/ because there are markdown files there
|
||||
- [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
|
||||
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)
|
||||
- [ ] when a rule matches a file, it will follow the defined settings in the dictionari
|
||||
- [x] in toc generator settings, per-file glob overrides in the `file`
|
||||
section (SPEC 4.10.2)
|
||||
- [ ] instead of current directory as default, find a fiona-settings.json
|
||||
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
|
||||
`fiona-settings.json` so table rules (MD055/MD056/MD058) run in
|
||||
`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
|
||||
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`
|
||||
- [ ] `date` tag
|
||||
- [ ] Quality signal: `confidence`
|
||||
- [ ] `contested` flag (true if claims are disputed)
|
||||
- [ ] Project documentation (SPEC 5.2)
|
||||
- [ ] Write `src/README.md` with project description
|
||||
- [ ] Setup instructions (`pip install -e .`)
|
||||
- [ ] Usage examples for librarian and mdoctor
|
||||
- [ ] Update `librarian/README.md` with actual usage info
|
||||
- [ ] Add `mdoctor/README.md`
|
||||
- [x] Root `README.md` links `SPEC.md`
|
||||
- [x] Root README and `AGENTS.md` document `bootstrap` and `bootstrap.ps1`
|
||||
- [ ] Refresh `librarian/README.md` and `mdoctor/README.md` for the
|
||||
current subcommands (`list`, `toc`, `chklint`, `fix`)
|
||||
- [ ] 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
|
||||
(`feat:`, `fix:`, `docs:`, ...) per project agent rule 8.1
|
||||
- [ ] `fiona-assistant wiki graph` make a class that can generate the obsidian style
|
||||
graph/link for md files association in html format (SPEC 3.1.4.)
|
||||
- [x] `fiona-assistant wiki graph` (SPEC 3.1.4): link parser, graph,
|
||||
HTML template, and CLI in `src/wiki/graph_generator.py`
|
||||
|
||||
## 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
|
||||
- [ ] Bash scripts — format TBD
|
||||
- [ ] 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)
|
||||
|
||||
- Tagging format for python files and bash scripts (SPEC 4.6.1)
|
||||
- Git wrapper location: `src/vcs/` vs `src/librarian/vcs.py` (SPEC 3.2)
|
||||
- make a class for generating html graph for md linkages like obsidian
|
||||
- Tagging format for python files and bash scripts (SPEC 4.8.1)
|
||||
- Git wrapper location: implemented at `src/gittool/git_tool.py` (SPEC 3.2)
|
||||
- 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.
|
||||
|
||||
Reference in New Issue
Block a user