Fix markdown documentation formatting issues#10
Conversation
Summary by CodeRabbit
WalkthroughPerform an editorial overhaul of AGENTS.md to add prescriptive Rust and Frontend (TypeScript) guidance and normalise formatting across multiple docs. Update dependency/error-handling/testing/runtime-validation/compiler/tooling guidance and retag code fences for better highlighting. Do not change code or public APIs. Changes
Sequence Diagram(s)Estimated code review effort🎯 2 (Simple) | ⏱️ ~8 minutes Poem
✨ Finishing Touches🧪 Generate unit tests
🪧 TipsChatThere are 3 ways to chat with CodeRabbit:
SupportNeed help? Create a ticket on our support page for assistance with any issues or questions. CodeRabbit Commands (Invoked using PR/Issue comments)Type Other keywords and placeholders
CodeRabbit Configuration File (
|
![sourcery-ai[bot]](https://avatars.githubusercontent.com/in/48477?s=60&v=4){kind=small}
There was a problem hiding this comment.
Sorry @leynos, you have reached your 24-hour rate limit for Sourcery. Please try again later
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 12
🔭 Outside diff range comments (15)
docs/wildside-high-level-design.md (1)
1168-1174: Fix broken citation sentence in Table 3 note.The sentence “Note: Cost estimates are based on pricing data from sources , and.83 …” has broken/missing references and will fail markdownlint/content checks.
Apply this diff to remove the broken references while keeping the intent:
-Note: Cost estimates are based on pricing data from sources , and.83 LLM costs +Note: Cost estimates are based on publicly available provider pricing at the time of writing. LLM costs are highly variable and represent the largest financial risk; the estimate assumes an average of 2 walks/month per user, 10 POIs per walk, and 1,000 tokens per POI description at an average cost of $10/M tokens.docs/repository-structure.md (3)
198-201: Remove stray “``” before code fences.The orphaned fence marker (“``”) before the dockerfile fence breaks Markdown.
Apply:
-`` - ```dockerfile # ===== Build stage ===== FROM rust:1.79-alpine AS build
228-234: Remove stray “``” before code fences.The orphaned fence marker (“``”) before the dockerfile fence breaks Markdown.
Apply:
-`` - ```dockerfile # ===== Build stage ===== FROM oven/bun:1 AS build
254-260: Remove stray “``” before code fences.The orphaned fence marker (“``”) before the compose fence breaks Markdown.
Apply:
-`` - ```yaml version: "3.9" services: backend:docs/cloud-native-ephemeral-previews.md (6)
108-116: Remove stray “```yaml” fence after closing an HCL block.A dangling opening fence (“```yaml”) appears right after an
hclfence closes. This breaks Markdown rendering.Apply:
- ```yaml - This configuration establishes the required providers and sets up the DigitalOcean provider.4 The DigitalOcean API token is defined as a sensitive variable, with the expectation that its value will be supplied via an
135-141: Remove stray “```yaml” fence after closing the VPC block.Another dangling fence (“```yaml”) appears after the
hclblock. Remove it.Apply:
- ```yaml - ### DOKS Cluster Resource (`digitalocean_kubernetes_cluster`)
1147-1153: Fix YAML spacing in docker/build-push-action step.Keys in the action inputs lack required spaces, which can confuse readers and tools.
Apply:
- context:. - file:./Dockerfile # Path to the application's Dockerfile + context: . + file: ./Dockerfile # Path to the application's Dockerfile
1263-1277: Fix shell syntax in “Commit and Push Manifests” step.The script has multiple syntax errors: “git add.”, missing space after
if, andcd...Apply:
- git add. - if! git diff --staged --quiet; then + git add . + if ! git diff --staged --quiet; then git commit -m "Deploy preview for PR #${{ github.event.number }} at tag ${{ github.sha }}" git push else echo "No changes to commit." fi - cd.. + cd ..
1310-1323: Fix teardown job guard condition.The “if; then” is invalid and will fail if used as reference. Guard with a directory existence check.
Apply:
- if; then + if [ -d "${MANIFESTS_DIR}" ]; then git config user.name "github-actions[bot]" git config user.email "41898282+github-actions[bot]@users.noreply.github.com" git rm -r ${MANIFESTS_DIR} git commit -m "Teardown preview environment for PR #${PR_NUMBER}" git push else echo "Directory ${MANIFESTS_DIR} does not exist. Nothing to tear down." fi
1231-1239: Set TLS hosts as an array in yq patch.
ingress.tls.hostsmust be an array. The current command assigns a scalar string.Apply:
- yq e ".spec.values.ingress.tls.hosts = \"${SUBDOMAIN}\"" -i ${MANIFESTS_DIR}/patch-main.yaml - yq e ".spec.values.ingress.tls.secretName = \"pr-${PR_NUMBER}-tls\"" -i ${MANIFESTS_DIR}/patch-main.yaml + yq e ".spec.values.ingress.tls = [{\"hosts\": [\"${SUBDOMAIN}\"], \"secretName\": \"pr-${PR_NUMBER}-tls\"}]" -i ${MANIFESTS_DIR}/patch-main.yamlAGENTS.md (5)
168-180: Surround the “Dependency Management (Rust)” heading with blank lines.Add a blank line before and after the heading to clear MD022.
Apply:
-### Dependency Management (Rust) +### Dependency Management (Rust) + ... -### Error Handling (Rust) + +### Error Handling (Rust)
291-299: Surround the “Error Handling (Frontend)” heading with blank lines.Add a blank line before the heading to satisfy MD022.
Apply:
- `Date.now()` or `Math.random()` directly in business logic. -### Error Handling (Frontend) + `Date.now()` or `Math.random()` directly in business logic. + +### Error Handling (Frontend)
316-326: Surround the “Dependency Management (Frontend)” heading and list with blank lines.Fix MD022/MD032 by adding blank lines before the heading and before the list.
Apply:
-### Dependency Management (Frontend) +### Dependency Management (Frontend) + - **Version policy**: Use caret requirements (`^x.y.z`) for all direct dependencies. Avoid `*`, `>=` or tag aliases like `latest`. Use tilde (`~x.y.z`) only with a documented justification.
403-413: Surround the “Release Discipline” heading and list with blank lines.Resolve MD022/MD032 for this section.
Apply:
-### Release Discipline +### Release Discipline + - **Conventional Commits + Changesets** for versioning (libraries) and change logs.
415-423: Surround the “Quick Checklist” list with blank lines.Add a blank line after the heading and before the list to satisfy MD032.
Apply:
-### Quick Checklist (Before Commit) -- `bun run fmt`, `bun run lint`, `bun run test` all clean; no Biome warnings; +### Quick Checklist (Before Commit) + +- `bun run fmt`, `bun run lint`, `bun run test` all clean; no Biome warnings; no TypeScript errors; coverage thresholds hold.
📜 Review details
Configuration used: CodeRabbit UI
Review profile: ASSERTIVE
Plan: Pro
💡 Knowledge Base configuration:
- Jira integration is disabled
You can enable these sources in your CodeRabbit configuration.
📒 Files selected for processing (4)
AGENTS.md(9 hunks)docs/cloud-native-ephemeral-previews.md(32 hunks)docs/repository-structure.md(10 hunks)docs/wildside-high-level-design.md(6 hunks)
🧰 Additional context used
📓 Path-based instructions (2)
**/*.md
📄 CodeRabbit Inference Engine (AGENTS.md)
**/*.md: Documentation must use en-GB-oxendict spelling and grammar (except LICENSE name)
Validate Markdown with make markdownlint
Run make fmt after doc changes to format Markdown and fix tables
Validate Mermaid diagrams by running make nixie
Wrap Markdown paragraphs and bullets at 80 columns; do not wrap tables/headings; code blocks at 120 columns; use dashes for bullets; use GFM footnotes
Files:
docs/cloud-native-ephemeral-previews.mddocs/repository-structure.mddocs/wildside-high-level-design.mdAGENTS.md
⚙️ CodeRabbit Configuration File
**/*.md: * Avoid 2nd person or 1st person pronouns ("I", "you", "we")
- Use en-GB-oxendict (-ize / -our) spelling and grammar
- Headings must not be wrapped.
- Documents must start with a level 1 heading
- Headings must correctly increase or decrease by no more than one level at a time
- Use GitHub-flavoured Markdown style for footnotes and endnotes.
- Numbered footnotes must be numbered by order of appearance in the document.
Files:
docs/cloud-native-ephemeral-previews.mddocs/repository-structure.mddocs/wildside-high-level-design.mdAGENTS.md
docs/**/*.md
📄 CodeRabbit Inference Engine (AGENTS.md)
docs/**/*.md: Use docs/ Markdown as the source of truth for requirements, dependencies, and architecture
Proactively update docs/ when decisions or dependencies change to keep documentation current
Keep small TS examples in docs that typecheck during builds; mirror production patterns
Files:
docs/cloud-native-ephemeral-previews.mddocs/repository-structure.mddocs/wildside-high-level-design.md
🪛 LanguageTool
docs/repository-structure.md
[style] ~86-~86: Redundant conjunctions can lead to confusion; consider removing a conjunction here.
Context: ...time (e.g., /api-docs/openapi.json) and/or emit a static spec/openapi.json via `...
(AND_OR)
[uncategorized] ~87-~87: Possible missing article found.
Context: ....jsonviabuild.rs` or a small bin. + Frontend runs orval under bun to generate a ...
(AI_HYDRA_LEO_MISSING_THE)
[style] ~94-~94: Consider using the typographical ellipsis character here instead.
Context: ...a::ToSchema)]. + api/handlers carry#[utoipa::path(...)]per route. +main.rsderives#[de...
(ELLIPSIS)
[style] ~102-~102: Would you like to use the Oxford spelling “centralizes”? The spelling ‘centralises’ is also correct.
Context: ...nctions. + A small src/api/fetcher.ts centralises base URL, auth, and error handling. + T...
(OXFORD_SPELLING_Z_NOT_S)
[misspelling] ~103-~103: This word is normally spelled as one.
Context: ...error handling. + TanStack Query hooks (hand-written or template‑generated) wrap the client ...
(EN_COMPOUNDS_HAND_WRITTEN)
[uncategorized] ~138-~138: Loose punctuation mark.
Context: ...ls. + packages/tokens/src/tokens.json: global primitives (color.*, space.*...
(UNLIKELY_OPENING_PUNCTUATION)
[uncategorized] ~140-~140: Loose punctuation mark.
Context: ...ges/tokens/src/themes/{light,dark}.json: semantic overrides (semantic.bg.defa...
(UNLIKELY_OPENING_PUNCTUATION)
[uncategorized] ~142-~142: Loose punctuation mark.
Context: ...ckages/tokens/build/style-dictionary.js: exports + dist/css/variables.css` (C...
(UNLIKELY_OPENING_PUNCTUATION)
[grammar] ~365-~365: The word ‘registry’ is not correct in this context. Use one of the suggestions or replace it with an appropriate verb.
Context: ...acts**: + Build backend image → push to registry. + Build frontend dist → upload to S...
(VB_TO_NN_DT)
AGENTS.md
[uncategorized] ~55-~55: Possible missing comma found.
Context: ...d demonstrating the behaviour being corrected both to validate the fix and to guard a...
(AI_HYDRA_LEO_MISSING_COMMA)
[grammar] ~69-~69: Did you mean “fewer”? The noun “characters” is countable.
Context: ... change (ideally 50 characters or less). - Body: Separate the subject from...
(FEWER_LESS)
[style] ~78-~78: Would you like to use the Oxford spelling “Recognizing”? The spelling ‘Recognising’ is also correct.
Context: ...# Refactoring Heuristics & Workflow - Recognising Refactoring Needs: Regularly assess t...
(OXFORD_SPELLING_Z_NOT_S)
[style] ~95-~95: Consider using “many”.
Context: ...change requiring small modifications in many different classes or functions. - **Post-Commit R...
(NUMEROUS_DIFFERENT)
[grammar] ~102-~102: “Change” is a singular noun. It appears that the verb form is incorrect.
Context: ...mit** after the functional change commit. - Ensure the refactoring adheres to th...
(PCT_SINGULAR_NOUN_PLURAL_VERB_AGREEMENT)
[style] ~237-~237: The double modal “requires installed” is nonstandard (only accepted in certain dialects). Consider “to be installed”.
Context: ...bun.lock; audit:snyk requires installed dependencies—run bun install before i...
(NEEDS_FIXED)
[style] ~288-~288: Would you like to use the Oxford spelling “Centralize”? The spelling ‘Centralise’ is also correct.
Context: ...signal in fetchers. - Time & RNG: Centralise now() and rng() adapters; never cal...
(OXFORD_SPELLING_Z_NOT_S)
🪛 markdownlint-cli2 (0.17.2)
AGENTS.md
77-77: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
78-78: Lists should be surrounded by blank lines
(MD032, blanks-around-lists)
168-168: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
181-181: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
265-265: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
285-285: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
291-291: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
316-316: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
403-403: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
415-415: Lists should be surrounded by blank lines
(MD032, blanks-around-lists)
⏰ Context from checks skipped due to timeout of 120000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (2)
- GitHub Check: build
- GitHub Check: build
🔇 Additional comments (4)
docs/wildside-high-level-design.md (1)
269-281: Validate Table Alignment and Formatting
- Confirm each row in the Competitive Feature Matrix uses exactly six columns (seven ‘|’ characters).
- Run your markdown formatter and linter (
make fmt&&make markdownlint) locally to ensure no table lines wrap.docs/cloud-native-ephemeral-previews.md (1)
87-97: Run linting and validate fenced code blocks
Runmake fmtandmake markdownlintin your local environment. Confirm all HCL, YAML and Bash code blocks in docs/cloud-native-ephemeral-previews.md are syntactically valid and copy-pasteable at these ranges:
- Lines 87–97
- Lines 125–136
- Lines 144–152
- Lines 200–210
- Lines 275–303
- Lines 318–353
- Lines 761–778
- Lines 829–860
- Lines 1088–1099
Fix any lint errors to ensure every fenced block compiles or parses without issues.
AGENTS.md (2)
1-467: Run Markdown toolchain locallyRun
make fmtandmake markdownlintin your local environment to confirm that AGENTS.md no longer triggers MD022, MD031, or MD032 errors.
288-290: Use Oxford “-ize” spelling per style guide.Change “Centralise” to “Centralize”.
Apply:
-- **Time & RNG**: Centralise `now()` and `rng()` adapters; never call +- **Time & RNG**: Centralize `now()` and `rng()` adapters; never callLikely an incorrect or invalid review comment.
There was a problem hiding this comment.
Actionable comments posted: 5
🔭 Outside diff range comments (5)
docs/repository-structure.md (2)
235-245: Remove second‑person phrasing in Dockerfile comments.Docs must avoid second‑person pronouns. Rewrite the comments to be impersonal.
Apply:
RUN apk add --no-cache musl-dev pkgconfig openssl-dev # adjust for your deps @@ -# build with musl (if your deps allow); otherwise use gnu + distroless base later +# build with musl (where dependencies allow); otherwise use gnu + distroless base laterAnd:
-RUN apk add --no-cache musl-dev pkgconfig openssl-dev # adjust for your deps +RUN apk add --no-cache musl-dev pkgconfig openssl-dev # adjust for required dependencies
278-282: Avoid “you” in guidance; keep en‑GB style.Replace second‑person phrasing with neutral language.
Apply:
-- For local dev, you can also serve via `vite dev` or a simple nginx container. +- For local development, serve via `vite dev` or a simple nginx container.docs/wildside-high-level-design.md (2)
146-152: Replace all stray inline numeric citations with GFM footnotesGrep detected multiple bare numerals across docs/wildside-high-level-design.md—including “6” at line 148, list markers like “1.” at line 227, and similar instances at lines 298, 321, 385, 827, 927, 1116, 1148, 1173, etc. Convert every inline number to a
[^n]reference and define each in the “Works Cited” section.Pinpoint locations:
- docs/wildside-high-level-design.md:148 (“6”)
- docs/wildside-high-level-design.md:227 (“1.” in numbered list)
- docs/wildside-high-level-design.md:298 (“Section 4” context)
- docs/wildside-high-level-design.md:321 (“T_max” list)
- docs/wildside-high-level-design.md:385 (“Section 5.4”)
- docs/wildside-high-level-design.md:827 (token usage footnote)
- docs/wildside-high-level-design.md:927 (PostGIS geometry footnote)
- docs/wildside-high-level-design.md:1116 (per-request cost “81”)
- docs/wildside-high-level-design.md:1148 (model cost “0.60”/“2.40”)
- docs/wildside-high-level-design.md:1173 (token assumption)
Example diff for line 148:
- OpenStreetMap as a primary data source 6, validates the viability of this + OpenStreetMap as a primary data source[^komoot-osm], validates the viability of thisThen append at the end of the file:
[^komoot-osm]: Komoot. “OpenStreetMap as a primary data source.” <URL to source>Repeat for each inline numeral, incrementing or naming the footnote key to match the referenced source. Ensure the “Works Cited” section lists every
[^n].
1169-1174: Fix malformed citations in cost estimation noteReplace the broken citation string—currently referencing [^46]—with the correct footnotes for Render, DigitalOcean Postgres and Anthropic pricing.
• File docs/wildside-high-level-design.md, line 1170
- Note: Cost estimates are based on pricing data from sources , and[^46] LLM costs + Note: Cost estimates are based on pricing data from [^25], [^41], and [^13]. LLM costsEnsure footnotes [^25] (Render), [^41] (DigitalOcean PostgreSQL) and [^13] (Anthropic API) are defined in the Works Cited section.
AGENTS.md (1)
228-253: Surround the “Project scripts (Bun)” list with a blank line (MD032).A list must be surrounded by blank lines. Add one after the “Project scripts (Bun):” line.
Apply:
-**Project scripts (Bun)**: -- `fmt`: `biome format --write .` +**Project scripts (Bun)**: + +- `fmt`: `biome format --write .`
📜 Review details
Configuration used: CodeRabbit UI
Review profile: ASSERTIVE
Plan: Pro
💡 Knowledge Base configuration:
- Jira integration is disabled
You can enable these sources in your CodeRabbit configuration.
📒 Files selected for processing (4)
.markdownlint.json(1 hunks)AGENTS.md(10 hunks)docs/repository-structure.md(4 hunks)docs/wildside-high-level-design.md(41 hunks)
🧰 Additional context used
📓 Path-based instructions (2)
**/*.md
📄 CodeRabbit Inference Engine (AGENTS.md)
**/*.md: Documentation must use en-GB-oxendict spelling and grammar (except LICENSE name)
Validate Markdown with make markdownlint
Run make fmt after doc changes to format Markdown and fix tables
Validate Mermaid diagrams by running make nixie
Wrap Markdown paragraphs and bullets at 80 columns; do not wrap tables/headings; code blocks at 120 columns; use dashes for bullets; use GFM footnotes
Files:
AGENTS.mddocs/wildside-high-level-design.mddocs/repository-structure.md
⚙️ CodeRabbit Configuration File
**/*.md: * Avoid 2nd person or 1st person pronouns ("I", "you", "we")
- Use en-GB-oxendict (-ize / -our) spelling and grammar
- Headings must not be wrapped.
- Documents must start with a level 1 heading
- Headings must correctly increase or decrease by no more than one level at a time
- Use GitHub-flavoured Markdown style for footnotes and endnotes.
- Numbered footnotes must be numbered by order of appearance in the document.
Files:
AGENTS.mddocs/wildside-high-level-design.mddocs/repository-structure.md
docs/**/*.md
📄 CodeRabbit Inference Engine (AGENTS.md)
docs/**/*.md: Use docs/ Markdown as the source of truth for requirements, dependencies, and architecture
Proactively update docs/ when decisions or dependencies change to keep documentation current
Keep small TS examples in docs that typecheck during builds; mirror production patterns
Files:
docs/wildside-high-level-design.mddocs/repository-structure.md
🧠 Learnings (2)
📚 Learning: 2025-07-28T19:14:46.188Z
Learnt from: CR
PR: leynos/femtologging#0
File: AGENTS.md:0-0
Timestamp: 2025-07-28T19:14:46.188Z
Learning: Before considering a change complete or proposing a commit, ensure it meets all quality gates: validated by relevant unittests and behavioural tests, bugfixes have a unittest, passes all tests, passes lint checks, adheres to formatting standards.
Applied to files:
AGENTS.md
📚 Learning: 2025-08-10T12:40:16.561Z
Learnt from: CR
PR: leynos/netsuke#0
File: AGENTS.md:0-0
Timestamp: 2025-08-10T12:40:16.561Z
Learning: Quality Gates: Before considering a change complete or proposing a commit, ensure it meets the following criteria: New functionality or changes in behaviour are fully validated by relevant unittests and behavioural tests.
Applied to files:
AGENTS.md
🪛 LanguageTool
AGENTS.md
[style] ~87-~87: Would you like to use the Oxford spelling “Recognizing”? The spelling ‘Recognising’ is also correct.
Context: ... Refactoring Heuristics & Workflow - Recognising Refactoring Needs: Regularly assess t...
(OXFORD_SPELLING_Z_NOT_S)
[style] ~104-~104: Consider using “many”.
Context: ...change requiring small modifications in many different classes or functions. - **Post-Commit R...
(NUMEROUS_DIFFERENT)
[grammar] ~111-~111: “Change” is a singular noun. It appears that the verb form is incorrect.
Context: ...mit** after the functional change commit. - Ensure the refactoring adheres to th...
(PCT_SINGULAR_NOUN_PLURAL_VERB_AGREEMENT)
[style] ~252-~252: The double modal “requires installed” is nonstandard (only accepted in certain dialects). Consider “to be installed”.
Context: ...bun.lock; audit:snyk requires installed dependencies—run bun install before i...
(NEEDS_FIXED)
[style] ~308-~308: Would you like to use the Oxford spelling “Centralize”? The spelling ‘Centralise’ is also correct.
Context: ...signal in fetchers. - Time & RNG: Centralise now() and rng() adapters; never cal...
(OXFORD_SPELLING_Z_NOT_S)
[uncategorized] ~447-~447: Loose punctuation mark.
Context: ...ecklist (Before Commit) - bun run fmt, bun run lint, bun run test all clea...
(UNLIKELY_OPENING_PUNCTUATION)
⏰ Context from checks skipped due to timeout of 120000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (2)
- GitHub Check: build
- GitHub Check: build
🔇 Additional comments (6)
docs/repository-structure.md (1)
138-140: LGTM: “centralizes/handwritten” matches Oxford “-ize” and compound style.Spelling aligns with en‑GB‑oxendict and prior feedback; keep as is.
docs/wildside-high-level-design.md (1)
1-888: LGTM: Footnotes, table captions, and spacing conform to style.The migration to GFM footnotes, table captions as headings, and spacing around lists/fences look correct and align with repo rules.
AGENTS.md (4)
179-203: LGTM: Rust dependency and error handling guidance is precise and actionable.Caret SemVer, prohibition of wildcards, and opaque error boundaries are well‑stated.
311-320: LGTM: Frontend error semantics follow sound patterns.Discriminated unions for domain errors and mapping at the UI boundary are correct.
445-455: LGTM: The “Quick Checklist” is aligned with house rules.The checks reflect Biome, TS, audit, AbortSignal, and docs/export expectations.
49-66: Confirm AGENTS.md passes markdown spacing rulesAll headings, lists, and fenced code blocks are properly surrounded by blank lines. No MD022, MD031, or MD032 violations remain across the file.
| { | ||
| "MD022": true, | ||
| "MD031": true, | ||
| "MD032": true, | ||
| "MD013": false | ||
| } |
There was a problem hiding this comment.
🛠️ Refactor suggestion
Re-enable MD013 with config matching house style (80/120 wrap).
The repo guideline mandates wrapping paragraphs/bullets at 80 columns and allowing code blocks up to 120. Disabling MD013 prevents enforcing this. Enable MD013 with appropriate options.
Apply:
{
"MD022": true,
"MD031": true,
"MD032": true,
- "MD013": false
+ "MD013": {
+ "line_length": 80,
+ "code_block_line_length": 120,
+ "tables": false,
+ "headings": false
+ }
}📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| { | |
| "MD022": true, | |
| "MD031": true, | |
| "MD032": true, | |
| "MD013": false | |
| } | |
| { | |
| "MD022": true, | |
| "MD031": true, | |
| "MD032": true, | |
| "MD013": { | |
| "line_length": 80, | |
| "code_block_line_length": 120, | |
| "tables": false, | |
| "headings": false | |
| } | |
| } |
🤖 Prompt for AI Agents
In .markdownlint.json lines 1-6, MD013 is disabled; re-enable it and configure
it to enforce an 80-character wrap for normal text while permitting up to 120
characters for code blocks by replacing the boolean with an object (e.g., set
MD013 to an object that sets "line_length": 80 and configures code-block
allowance to 120), keeping the other rules unchanged.
| - **Recognising Refactoring Needs:** Regularly assess the codebase for potential | ||
| refactoring opportunities. Consider refactoring when you observe: | ||
| - **Long Methods/Functions:** Functions or methods that are excessively long | ||
| - **Long Methods/Functions:** Functions or methods that are excessively long | ||
| or try to do too many things. | ||
| - **Duplicated Code:** Identical or very similar code blocks appearing in | ||
| - **Duplicated Code:** Identical or very similar code blocks appearing in | ||
| multiple places. |
There was a problem hiding this comment.
🛠️ Refactor suggestion
Insert a blank line before the refactoring bullet list (MD032).
A list must be preceded by a blank line. Add one between the sentence ending “observe:” and the first bullet.
Apply:
- refactoring opportunities. Consider refactoring when you observe:
-- **Long Methods/Functions:** Functions or methods that are excessively long
+ refactoring opportunities. Consider refactoring when you observe:
+
+- **Long Methods/Functions:** Functions or methods that are excessively longCommittable suggestion skipped: line range outside the PR's diff.
🧰 Tools
🪛 LanguageTool
[style] ~87-~87: Would you like to use the Oxford spelling “Recognizing”? The spelling ‘Recognising’ is also correct.
Context: ... Refactoring Heuristics & Workflow - Recognising Refactoring Needs: Regularly assess t...
(OXFORD_SPELLING_Z_NOT_S)
🤖 Prompt for AI Agents
In AGENTS.md around lines 87 to 92, the bulleted list following the sentence
ending "observe:" is not separated by a blank line (MD032); insert a single
blank line between that sentence and the first list item so the list is properly
preceded by an empty line, then save and verify the markdown linter no longer
flags MD032.
|
|
||
| ## Refactoring Heuristics & Workflow | ||
|
|
||
| - **Recognising Refactoring Needs:** Regularly assess the codebase for potential |
There was a problem hiding this comment.
🧹 Nitpick (assertive)
Use Oxford “-ize”: change “Recognising” → “Recognizing”.
Align with en‑GB‑oxendict spelling.
Apply:
-**Recognising Refactoring Needs:** Regularly assess the codebase for potential
+**Recognizing Refactoring Needs:** Regularly assess the codebase for potential📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| - **Recognising Refactoring Needs:** Regularly assess the codebase for potential | |
| - **Recognizing Refactoring Needs:** Regularly assess the codebase for potential |
🧰 Tools
🪛 LanguageTool
[style] ~87-~87: Would you like to use the Oxford spelling “Recognizing”? The spelling ‘Recognising’ is also correct.
Context: ... Refactoring Heuristics & Workflow - Recognising Refactoring Needs: Regularly assess t...
(OXFORD_SPELLING_Z_NOT_S)
🤖 Prompt for AI Agents
In AGENTS.md around line 87, the word "Recognising" uses en-GB spelling but the
project requires Oxford "-ize" (en-GB-oxendict) conventions; replace
"Recognising Refactoring Needs:" with "Recognizing Refactoring Needs:" (and
update any other occurrences of "Recognising" to "Recognizing") to align
spelling across the document.
| - Perform the refactoring as a **separate, atomic commit** *after* the | ||
| functional change commit. | ||
| - Ensure the refactoring adheres to the testing guidelines (behavioural tests | ||
| - Ensure the refactoring adheres to the testing guidelines (behavioural tests | ||
| pass before and after, unit tests added for new units). | ||
| - Ensure the refactoring commit itself passes all quality gates. | ||
| - Ensure the refactoring commit itself passes all quality gates. | ||
|
|
There was a problem hiding this comment.
🛠️ Refactor suggestion
Nest the action list under “Separate Atomic Refactors”.
Indent the two step bullets to make them children of the “Separate Atomic Refactors” item. This improves structure and satisfies markdownlint expectations for nested lists.
Apply:
-**Separate Atomic Refactors:** If refactoring is deemed necessary:
-- Perform the refactoring as a **separate, atomic commit** *after* the
+**Separate Atomic Refactors:** If refactoring is deemed necessary:
+ - Perform the refactoring as a **separate, atomic commit** *after* the
functional change commit.
-- Ensure the refactoring adheres to the testing guidelines (behavioural tests
+ - Ensure the refactoring adheres to the testing guidelines (behavioural tests
pass before and after, unit tests added for new units).
- - Ensure the refactoring commit itself passes all quality gates.
+ - Ensure the refactoring commit itself passes all quality gates.📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| - Perform the refactoring as a **separate, atomic commit** *after* the | |
| functional change commit. | |
| - Ensure the refactoring adheres to the testing guidelines (behavioural tests | |
| - Ensure the refactoring adheres to the testing guidelines (behavioural tests | |
| pass before and after, unit tests added for new units). | |
| - Ensure the refactoring commit itself passes all quality gates. | |
| - Ensure the refactoring commit itself passes all quality gates. | |
| - **Separate Atomic Refactors:** If refactoring is deemed necessary: | |
| - Perform the refactoring as a **separate, atomic commit** *after* the functional change commit. | |
| - Ensure the refactoring adheres to the testing guidelines (behavioural tests pass before and after, unit tests added for new units). | |
| - Ensure the refactoring commit itself passes all quality gates. |
🧰 Tools
🪛 LanguageTool
[grammar] ~111-~111: “Change” is a singular noun. It appears that the verb form is incorrect.
Context: ...mit** after the functional change commit. - Ensure the refactoring adheres to th...
(PCT_SINGULAR_NOUN_PLURAL_VERB_AGREEMENT)
🤖 Prompt for AI Agents
In AGENTS.md around lines 110 to 115, the two step bullets are not indented as
children under the "Separate Atomic Refactors" list item; indent those two lines
by one additional list-level (e.g., 4 spaces or a tab) so they become nested
bullets under "Separate Atomic Refactors", keep the existing wording and
punctuation, and verify the markdown renders as a nested list and passes
markdownlint.
| - **Cancellation**: Accept `AbortSignal` for any async that can hang (fetches, | ||
| long UI work). Wire signals through TanStack Query via `signal` in fetchers. | ||
| - **Time & RNG**: Centralise `now()` and `rng()` adapters; never call | ||
| `Date.now()` or `Math.random()` directly in business logic. | ||
|
|
There was a problem hiding this comment.
🧹 Nitpick (assertive)
Use Oxford “-ize”: change “Centralise” → “Centralize”.
Keep spelling consistent with the style guide.
Apply:
-**Time & RNG**: Centralise `now()` and `rng()` adapters; never call
+**Time & RNG**: Centralize `now()` and `rng()` adapters; never call📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| - **Cancellation**: Accept `AbortSignal` for any async that can hang (fetches, | |
| long UI work). Wire signals through TanStack Query via `signal` in fetchers. | |
| - **Time & RNG**: Centralise `now()` and `rng()` adapters; never call | |
| `Date.now()` or `Math.random()` directly in business logic. | |
| - **Cancellation**: Accept `AbortSignal` for any async that can hang (fetches, | |
| long UI work). Wire signals through TanStack Query via `signal` in fetchers. | |
| - **Time & RNG**: Centralize `now()` and `rng()` adapters; never call | |
| `Date.now()` or `Math.random()` directly in business logic. |
🧰 Tools
🪛 LanguageTool
[style] ~308-~308: Would you like to use the Oxford spelling “Centralize”? The spelling ‘Centralise’ is also correct.
Context: ...signal in fetchers. - Time & RNG: Centralise now() and rng() adapters; never cal...
(OXFORD_SPELLING_Z_NOT_S)
🤖 Prompt for AI Agents
In AGENTS.md around lines 306 to 310, the word "Centralise" uses British
spelling; change it to Oxford "-ize" form "Centralize" to match the project's
style guide and keep spelling consistent across the document. Update that single
word while leaving surrounding text unchanged.
1 participant
Summary
AGENTS.mdTesting
make fmtmake check-fmtmake lintmake testmake markdownlint(fails: AGENTS.md requires additional cleanup)https://chatgpt.com/codex/tasks/task_e_689e50e7461483228a7ce1f06995cddd