This is the public high-level direction of development. The detailed working plan lives in TASKS.internal.md, is not published, and remains the source of the exact order of internal tasks.
A capability described here counts as planned until its implementation is confirmed by code, tests and documentation.
Before any package is installed, the owner approves:
- Python 3.12;
- the environment and dependency manager;
- the runtime dependencies;
- the development dependencies;
- the build dependencies;
- the exact commands for a reproducible installation.
Before a working graphical interface is created, images of the following must be shown and approved:
- opening a project;
- the radial map;
- the full review list;
- the diff and the edit plan;
- the archive and history;
- the settings and rules.
Before the first apply operation the following are required:
- a threat model;
- a security review of paths and temporary files;
- an approved archive schema;
- atomic write;
- recovery after a failure;
- trials of a stale plan and of conflicts.
- project instructions and skills;
- private working files excluded from Git;
- public documentation separated from the internal plan;
- no dependency installation before the environment is approved.
- a reproducible Python 3.12 environment;
- separated dependency groups;
- pytest, Ruff, type checking and coverage;
- the initial package structure.
- a shared navigation model;
- mockups of every main screen;
- a check of the behaviour on a large project;
- explicit approval by the owner.
- typed core entities;
- the project identifier;
- the source file and comment model;
- the decision and edit plan model;
- the SQLite schema and the schema version;
- snapshots, cleanup sessions and the archive;
- no mutating operations.
- directory traversal;
- mandatory and configurable exclusions;
.gitignore;- binary, large and non-standard files;
- compound extensions;
- test classification;
- the project tree.
- the approved set for NetRuleRouter: Rust, C, C++, Qt/QML, JavaScript and generic SQL;
- seven Tree-sitter grammars:
rust,c,cpp,qmljs,xmlfor.qrc,javascriptandsql; - an isolated grammar supplier and a user cache outside the opened project;
- comment extraction;
- standalone, inline, documentation and protected comments, and the TODO family;
- fixtures, including groups of consecutive comments and exact byte ranges;
- a JSON report;
- no applying changes, no user decisions and no writing into the opened project.
Once the initial set had stabilised, standalone parser-backed adapters for Python, TypeScript/TSX, HTML, CSS, POSIX shell, PowerShell, PostgreSQL and T-SQL were added. Oracle SQL/PLSQL still requires an adapter of its own.
- the
app.rc.infixture; - matching of compound names;
- a built-in conservative
.rc/.rc.inprofile for verified text only; - precise manual selection through the ordinary
EditPlan, with no rules and no bulk cleanup; - a ban on unsafe removal by regular expressions and on working around a Tree-sitter error.
- the schema version;
- the project identifier;
- file and directory snapshots;
- application and test code metrics;
- comparison of two states.
ProjectNode,ProjectMetrics,ProjectMapViewModel;- stable identifiers;
- a shared scope, navigation and the path chain;
- metric selection and the test filter;
- a text rendering for the command-line interface;
- a Qt radial diagram prototype;
- a trial on thousands of small files.
- the rule protocol;
- reasons, indicators and risk;
- the conservative profile;
- the first safe rules;
- a set of false positives.
The first implementation is ready: Finding remains an analysis result without a user
decision, and the conservative profile covers an empty or punctuation-only comment
and exact duplicates within one file. The more subjective early rules are available
only through an explicit project policy. Structural markers and dates serve as
separate review-priority indicators.
- the results table;
- sorting, search and filters;
- selecting items and groups;
- viewing the source;
- moving between the map, the tree and the list.
- user decisions;
- a serialisable plan;
- conflict checking;
- diffs;
- expected metrics;
- detection of a stale file;
- the dry run.
- the cleanup session;
- archive records;
- atomic write;
- batch apply;
- checksums;
- a rescan;
- restore;
- the threat model and a security review.
- comparison of the current and the previous state;
- code and comment changes;
- separation of tests and application code;
- CommentRake's own changes and external changes;
- the basis for an arbitrary date range.
- a single working command
commentrake scan [PROJECT_ROOT]with no interactive questions; - scan, metrics, scope and the test filter;
- a text summary and versioned JSON;
- stable exit codes for automation;
- no writing into the opened project and no history by default.
The plan, the dry run, apply, the archive, history and restore get their own domain models in later stages and are not part of the early CLI.
- an approved priority list;
- additions only through a language adapter;
- protected constructs and fixtures for every language;
- compound names and the per-language test conventions.
- approved mockups;
- the tree and the radial diagram;
- the full list;
- viewing the source;
- the diff and the plan;
- the archive, history and settings;
- Russian and English localisation;
- background work and cancellation;
- a check that the interface starts.
- shared project map state;
- a proportional tree or a linear breakdown;
- moving in and up;
- adjusting the level of detail;
- the review list;
- the plan, apply, the archive and history;
- keyboard control.
- stable JSON schemas;
- a policy against bringing the noise back;
- a public CommentRake skill;
- safe usage examples;
- instructions installed only explicitly.
- a provider interface;
- request and result models;
- an empty local provider;
- privacy rules;
- no obligation to implement network translation.
- Windows, Linux and macOS;
- paths, encodings and permissions;
- symbolic links and atomic write;
- SQLite locks;
- high pixel density;
- a comparison of PyInstaller and Nuitka once the application has stabilised;
- packaging PySide6, the Tree-sitter grammars, SQLite and the translations;
- a start-up check on a clean system;
- dependency licences, size and start-up time.
- the README and the detailed documentation;
- Apache License 2.0;
- the contribution and security policies;
- a guide to languages and rules;
- public skills;
- removal of internal materials;
- a check for secrets;
- builds and release notes.
The user can:
- open a project and scan it safely;
- manage exclusions and
.gitignore; - see the non-standard supported files;
- tell application code from test code;
- see the protected kinds of comment;
- explore the project map and the full list;
- choose decisions and create an edit plan;
- review the diff and perform a dry run;
- apply the changes safely;
- open the archive and restore changes without losing later edits;
- save a snapshot and compare at least two states;
- work through the command-line interface and the approved graphical interface;
- use the same map and review model in the terminal interface;
- obtain machine-readable data without an agent editing files directly.
- Correctness, safety and explainability matter more than speed and the number of removed lines.
- Every confirmed false result becomes a regression fixture.
- The interfaces use one core and shared models.
- Public schemas are versioned.
- Failing tests are not hidden and not weakened for the sake of a passing result.
- New dependencies and any widening of the product's boundaries require a justified task.
- Git commits, pushing changes and releases happen only at the owner's direct request.