tech: define focused maintenance roadmap

[HamidMolareza]

Context

This repository is small and still useful as an internal/shared pre-commit utility, but it should not stay positioned as a generic "some hooks for pre-commit" collection. The most valuable direction is to make it a focused set of practical quality gates, especially for .NET/Python projects that are used across Payadel/HamidMolareza repositories.

Related existing item:

• feat: add coverage test for dotnet projects #42

Recommended Direction

Reposition the project around concrete, reusable pre-commit quality gates instead of broad hook collection maintenance.

The first useful milestone should be:

• keep the existing run-scripts and document-oriented hooks;
• harden their behavior enough for external/public use;
• add a focused .NET coverage gate as the first new hook;
• document usage through real project examples.

Technical Suggestions

1. Add a dotnet-coverage hook

This is the most promising new feature because it matches the maintainer's main stack and the existing open issue.

Expected capabilities:

• accept --path for solution/project/test-project path;
• accept --min for minimum acceptable coverage percentage;
• run coverage in a deterministic way;
• fail with clear output when coverage is below the threshold;
• support CI/pre-push usage with pass_filenames: false;
• document usage for ASP.NET Core and NuGet package repositories.

Possible future options:

• --configuration;
• --framework;
• --filter;
• --report-format;
• --coverage-file;
• --no-restore;
• --timeout.

2. Harden run-scripts

Current behavior is useful, but it should be safer and more predictable before being promoted as a public hook.

Suggested changes:

• avoid shell=True for normal script execution;
• build subprocess calls from argument arrays instead of string concatenation;
• preserve script argument quoting correctly;
• add optional timeout support;
• add optional working directory support;
• print command, stdout, stderr, and exit code in a readable failure format;
• keep deterministic execution order for files collected from directories;
• decide and document whether directory collection is recursive or non-recursive;
• add tests for spaces in file paths and arguments.

3. Improve document-oriented

The idea is useful, but the current model is too simple for long-term use.

Suggested changes:

• compare against the correct upstream/merge-base for push checks;
• handle new branches explicitly;
• handle renamed/deleted files deliberately;
• support a config file for source/document pattern mapping;
• allow mapping source areas to their expected documentation areas;
• support a clear skip mechanism with documented examples;
• improve failure output so it shows which changed source files require documentation updates.

Example future config shape:

rules:
  - source:
      - "src/**/*.py"
      - "src/**/*.cs"
    docs:
      - "README.md"
      - "docs/**/*.md"

4. Improve public project presentation

The current README is functional, but the project needs clearer positioning.

Suggested changes:

• replace the generic description with a concrete value proposition;
• add a "When should I use this?" section;
• add a quick-start example for each hook;
• add one realistic .pre-commit-config.yaml example for a .NET repository;
• document the maintenance policy and supported Python versions;
• add a short comparison between run-scripts and a regular local hook script.

5. Strengthen tests and CI around behavior

Suggested checks:

• test command argument quoting;
• test paths with spaces;
• test failure output formatting;
• test push/no-upstream behavior for document-oriented;
• run the test suite across the supported Python versions;
• keep coverage requirements, but focus on behavior tests rather than only line coverage.

6. Dogfood in template repositories

After the hook behavior is stable, apply it in repositories where it can prove value.

Candidate repositories:

• ConsoleSharpTemplate;
• NugetPackageTemplate;
• existing Python package templates;
• small ASP.NET Core sample repositories.

Suggested Milestone

A practical first milestone could be:

• Implement dotnet-coverage from feat: add coverage test for dotnet projects #42.
• Replace unsafe string-based command execution in run-scripts.
• Add tests for argument quoting and paths with spaces.
• Add a real .NET usage example to README.
• Update the repository About/description to reflect the focused direction.

Non-goals

• Do not turn this into a large generic hook marketplace.
• Do not spend time only updating dependency versions without improving the actual hook behavior.
• Do not add many weak hooks; prefer a few hooks that are useful in real projects.