grounded-lint 0.7.1__tar.gz

grounded_lint-0.7.1/CHANGELOG.md

@@ -0,0 +1,114 @@
+# Changelog
+
+All notable changes to `grounded` are documented here. Format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
+
+## [0.7.1] - 2026-09-21
+
+### Changed
+- Distribution renamed to `grounded-lint` on PyPI (bare `grounded` was
+  claimed). Command (`grounded`), import package, and action behavior
+  unchanged.
+
+## [0.7.0] - 2026-09-21
+
+### Added
+- `grounded mcp`: stdlib MCP server over stdio (initialize negotiation,
+  tools/list, tools/call, ping) with `check_path` and `explain_checker`
+  tools; paths confined to the server root. Verified with an independent
+  Node client against the spec.
+- Symbol renames in `grounded fix`: exactly one similar (ratio 0.75+),
+  same-directory candidate, or nothing is touched. Proven on the case
+  that killed naive similarity autofix.
+- Per-symbol defining files in the repo index (powers scope proximity).
+
+### Changed
+- General Markdown verification declined after measurement (199 import
+  claims trivially valid, flag claims mostly external tools on axios
+  docs); overlaps readme-ci, doccident, doc-drift, and docverity.
+
+## [0.6.0] - 2026-09-17
+
+### Added
+- C support (`.c`/`.h`): functions incl. split declarations and K&R style,
+  types, macros, function-pointer members, `#include` maps.
+- Parallel scanning (`--jobs N`, auto by file count; identical output).
+- VS Code task snippet using the bundled problem matcher.
+
+### Changed
+- JS index covers default exports, `module.exports` members, TS
+  interfaces/types (no benchmark delta).
+
+## [0.5.0] - 2026-09-17
+
+### Added
+- Go support: functions, types, and imports across all four checkers.
+- `grounded fix [--dry-run]`: rewrites unambiguous stale file paths
+  (unique same-basename match, comment lines only).
+- Inline suppressions: `# grounded-disable: <id>` (`//` form for JS/TS/Go).
+- First-party GitHub Action with problem matchers (verified live on a
+  test PR); pre-commit hook definition.
+
+### Changed
+- File references use exact-path semantics and list same-named candidates;
+  ticket-anchored history notes stay silent.
+- Markdown files are not scanned: measured zero file-reference hits across
+  160 documentation files, so no evidence of value (rejected).
+- Symbol rename autofix rejected: string-similarity ranking picked the
+  wrong target on a real case; suggestions stay advisory-only.
+
+## [0.4.1] - 2026-09-17
+
+### Fixed
+- CI demo-fixture count to match current fixtures. No product changes.
+
+## [0.4.0] - 2026-09-17
+
+### Added
+- Inline suppressions: `# grounded-disable: <id>` (`//` form for JS/TS).
+- First-party GitHub Action (`action.yml`) with problem matchers for inline
+  PR annotations; verified live on a test PR.
+- Pre-commit hook definition (`.pre-commit-hooks.yaml`).
+
+### Changed
+- Commented-code suppression gate tightened (prose with a few keywords no
+  longer qualifies).
+
+## [0.3.0] - 2026-09-17
+
+### Added
+- `grounded baseline`: record current findings to `.grounded-baseline.json`.
+  `scan --baseline FILE` then reports only new findings. Fingerprints hash
+  checker, path, and claim text (never line numbers), so unrelated edits
+  that shift lines do not churn the file. `--show-baselined` lists
+  suppressed findings.
+- `scan --changed [BASE]` (default: `HEAD`): report only findings on lines
+  changed relative to BASE, for PR gates and pre-commit use. The tree is
+  still fully scanned; reporting is filtered. Fails loudly outside git.
+- `.gitignore`, contributor fixture guidelines in README.
+
+## [0.2.0] - 2026-09-17
+
+### Changed
+- Deleted `param-mismatch`, `raises-mismatch`, `return-mismatch`,
+  `commented-code`: verified redundant with darglint/pydoclint,
+  eslint-plugin-jsdoc, and Ruff ERA001. `explain <id>` now routes to them.
+- Rebuilt `stale-symbol-ref`: import-aware (stdlib/deps/relative), same-file
+  scope proxy, Sphinx/JSDoc-tag scrubbing, dunder-typo class, verb-gated
+  bare calls, acronym/negation/ticket gates, `difflib` rename suggestions.
+- Hardened `stale-file-ref`: repo-scope rule, alphabetic extension list,
+  placeholder + illustrative-example handling.
+- Tightened commented-code suppression gate (suppression-only use).
+- Excluded TypeScript declaration files (`.d.ts`/`.d.cts`/`.d.mts`).
+- Measured on requests/axios/django: 844 → 42 findings; the 1 remaining
+  lie is a confirmed true rename-rot.
+
+### Added
+- `examples/v2demo`: 4-file fixture tree (8 intended findings, designed
+  silences for every suppression rule).
+- MIT `LICENSE`, CI workflow (tests + self-scan gate), this file.
+
+## [0.1.0] - 2026-09-16
+
+Initial release: 8 checkers. Superseded by 0.2.0, which narrowed scope to
+reference checks and removed contract checks covered by other linters.

grounded_lint-0.7.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 gonisulaimann
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

grounded_lint-0.7.1/MANIFEST.in

@@ -0,0 +1,7 @@
+include README.md CHANGELOG.md LICENSE
+include src/grounded/py.typed
+recursive-include examples *.py *.js
+prune src/grounded.egg-info
+prune build
+prune dist
+global-exclude __pycache__ *.py[cod]

grounded_lint-0.7.1/PKG-INFO

@@ -0,0 +1,302 @@
+Metadata-Version: 2.4
+Name: grounded-lint
+Version: 0.7.1
+Summary: Find dangling references in code comments. Deterministic, offline, zero dependencies.
+License: MIT License
+        
+        Copyright (c) 2026 gonisulaimann
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+        
+Project-URL: Homepage, https://github.com/gonisulaimann/Grounded
+Project-URL: Changelog, https://github.com/gonisulaimann/Grounded/blob/main/CHANGELOG.md
+Keywords: lint,comments,documentation,static-analysis,tech-debt
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Quality Assurance
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# grounded
+
+[![CI](https://github.com/gonisulaimann/Grounded/actions/workflows/ci.yml/badge.svg)](https://github.com/gonisulaimann/Grounded/actions/workflows/ci.yml)
+[![PyPI version](https://badge.fury.io/py/grounded-lint.svg)](https://pypi.org/project/grounded-lint/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+ <a href="https://www.ko-fi.com/gonisulaiman"><img src="https://srv-cdn.himpfen.io/badges/kofi/kofi-flat.svg" alt="Ko-Fi" /></a>
+
+Find dangling references in code comments. If a comment names a function
+that no longer exists, or a file that is not there, `grounded` reports it
+with the claim, the evidence, and a suggested fix.
+
+```console
+$ grounded scan ./src
+LIE src/app.py:9 [stale-symbol-ref] Comment references `ghost_service` which is not defined here
+    claim: `ghost_service()`
+    evidence: `ghost_service` is not defined, imported, or used in this file,
+              and no definition was found in 84 indexed source files.
+    fix: Update the comment to the current name, or remove the reference.
+```
+
+Zero dependencies. No network access. Works on Python, JavaScript/TypeScript, Go, and C.
+
+## Install
+
+Requires Python 3.10 or later.
+
+```console
+pip install grounded-lint
+```
+
+From source:
+
+```console
+git clone https://github.com/gonisulaimann/Grounded.git
+cd Grounded
+pip install -e .
+```
+
+## Usage
+
+```console
+grounded scan [PATH] [--format terminal|json|sarif|html] [--output FILE]
+              [--fail-on lie|drift|smell|never]
+              [--enable CHECKER,...] [--disable CHECKER,...]
+              [--baseline FILE] [--show-baselined]
+              [--changed [BASE]]
+              [--config grounded.toml] [--no-color] [--quiet]
+              [--jobs N]
+grounded baseline [PATH] [--output FILE]  # record findings for delta gating
+grounded fix [PATH] [--dry-run]  # rewrite unambiguous stale file paths
+grounded list [PATH]       # show files that would be scanned
+grounded explain CHECKER   # describe a checker (including removed ones)
+grounded init [--force]    # write a starter grounded.toml
+```
+
+`grounded scan` exits with status `1` when any finding meets `--fail-on`
+(default: `lie`), `0` otherwise. Point it at CI and gate on the default.
+
+Example output formats for tooling: `--format json` for scripts,
+`--format sarif` for GitHub code scanning, `--format html` for a
+self-contained report page (no external assets, works opened from disk).
+
+Large trees scan in parallel automatically (32+ files); `--jobs N`
+overrides, `--jobs 1` forces serial. Output is identical either way.
+
+In VS Code, wire the bundled problem matcher through a task
+(`.vscode/tasks.json`, paths relative to the workspace):
+
+```json
+{
+  "version": "2.0.0",
+  "tasks": [
+    {
+      "label": "grounded",
+      "type": "shell",
+      "command": "grounded scan . --no-color",
+      "problemMatcher": {
+        "owner": "grounded",
+        "pattern": [
+          {
+            "regexp": "^(LIE|DRIFT|SMELL)\\s+(.+?):(\\d+)\\s+\\[(.+?)\\]\\s+(.*)$",
+            "file": 2,
+            "line": 3,
+            "code": 4,
+            "message": 5
+          }
+        ]
+      }
+    }
+  ]
+}
+```
+
+## Adopting on an existing codebase
+
+Two mechanisms, composable. Both keep the full-tree scan and filter
+reporting only.
+
+Record a baseline once, commit it, gate on the delta:
+
+```console
+grounded baseline . --output .grounded-baseline.json   # record today
+git add .grounded-baseline.json
+grounded scan . --baseline .grounded-baseline.json     # new findings only
+```
+
+Fingerprints cover checker, path, and claim text, not line numbers, so
+unrelated edits do not churn the file. Editing the offending line itself
+re-triggers the gate. `--show-baselined` lists suppressed findings.
+
+Gate pull requests on changed lines only:
+
+```console
+grounded scan . --changed                # uncommitted work vs HEAD
+grounded scan . --changed origin/main    # branch vs base (CI)
+```
+
+Untracked files are fully reported. Outside a git repo, or with an
+unresolvable base, `--changed` exits `2` with the git error instead of
+silently scanning everything.
+
+## Rules
+
+| ID | Default severity | What it reports |
+|---|---|---|
+| `stale-symbol-ref` | lie (error) | A comment names a call that resolves nowhere: not defined in the repo, not imported in the file, not used in the file, not a builtin or keyword. Prints rename suggestions when a close match exists. |
+| `stale-file-ref` | lie (error) | A comment claims a path inside the repo tree that does not exist. References to other projects, frameworks, template namespaces, and placeholder paths are ignored. |
+| `number-drift` | drift (warning) | A comment states a magic number (timeout, port, limit, threshold) that disagrees with adjacent code. |
+| `fragile-anchor` | smell (note) | `line 42` anchors, `see above` / `see below` without a symbol, and workaround markers (`HACK`, `XXX`, `workaround`) with no ticket or expiry condition. |
+
+A rule stays silent unless the contradiction is mechanical. Imported names,
+standard library names, parameters, locals, attributes, docstring field
+lists (`:param:`, `@param`), and illustrative examples ("For example …")
+never produce findings.
+
+## Configuration
+
+`grounded init` writes a starter file. Settings also load from
+`pyproject.toml` under `[tool.grounded]`.
+
+```toml
+# grounded.toml
+disable = ["fragile-anchor"]
+fail_on = "lie"
+ignore_dirs = ["docs", "sandbox"]
+ignore_files = ["generated.py"]
+```
+
+Suppress a single accepted finding where it sits (reviewable, local):
+
+```python
+# Calls `legacy_parse()` for old dumps.  # grounded-disable: stale-symbol-ref
+```
+
+```js
+// Calls `legacyParse()` for old dumps.  // grounded-disable: stale-symbol-ref
+```
+
+## CI, pre-commit, and GitHub Action
+
+Gate pull requests with the first-party Action (inline PR annotations
+included via problem matchers):
+
+```yaml
+- uses: gonisulaimann/Grounded@v0.7.0
+  with:
+    changed-base: origin/main   # new findings on edited lines only
+    fail-on: lie
+```
+
+Or with a baseline file for whole-tree delta gating:
+
+```yaml
+- uses: gonisulaimann/Grounded@v0.7.0
+  with:
+    baseline: .grounded-baseline.json
+```
+
+As a pre-commit hook (runs on uncommitted changes):
+
+```yaml
+repos:
+  - repo: https://github.com/gonisulaimann/Grounded
+    rev: v0.7.0
+    hooks:
+      - id: grounded
+```
+
+SARIF upload for code scanning: run with `--format sarif --output
+results.sarif`, then upload with `github/codeql-action/upload-sarif`.
+
+## Coding agents (MCP)
+
+`grounded` serves itself over stdio as a Model Context Protocol server,
+so agents can verify references instead of trusting them:
+
+```json
+{
+  "mcpServers": {
+    "grounded": { "command": "grounded", "args": ["mcp", "--root", "."] }
+  }
+}
+```
+
+Two tools: `check_path` (scan a path under the server root; paths cannot
+escape it) and `explain_checker`. Protocol versions `2025-03-26` through
+`2025-06-18` are negotiated per the spec; logs go to stderr, stdout
+carries only MCP messages.
+
+## Non-goals
+
+Docstring contracts (parameter lists, return sections, raised exceptions)
+are covered precisely by [darglint](https://github.com/terrencepreilly/darglint)
+and [pydoclint](https://github.com/jsh9/pydoclint) for Python and
+[eslint-plugin-jsdoc](https://github.com/gajus/eslint-plugin-jsdoc) for
+JavaScript/TypeScript. Commented-out code is covered by
+[Ruff ERA001](https://docs.astral.sh/ruff/rules/commented-out-code/) and
+equivalent ESLint rules. `grounded` intentionally does not duplicate them;
+`grounded explain <id>` points at the right tool for each removed check.
+
+## Limitations
+
+- Unformatted, unverbed name mentions are skipped. A rename noted without
+  backticks or a reference verb ("calls", "see", "uses") will be missed.
+  This trades recall for precision.
+- Names imported from anywhere are treated as known elsewhere, including
+  cross-module renames.
+- Framework namespaces (template paths, URL names) are out of scope; such
+  references stay silent instead of guessed.
+- JavaScript/TypeScript, Go, and C analysis is syntactic (imports plus
+  identifiers), not a full type graph.
+- External references stay silent only when recognized: stdlib and POSIX
+  names, imports, and same-file identifiers. References to vendored code,
+  kernel idioms, platform APIs, paper algorithms, and prose verbs in
+  parentheses (`forks()`) can still report; judge those on sight.
+- Rename suggestions use string similarity only; the first guess can miss.
+  `grounded fix` applies a symbol rename only with exactly one similar,
+  same-directory candidate.
+- `grounded fix` rewrites stale file paths only on unambiguous
+  same-basename matches in comments (never docstrings, never ties).
+
+## Development
+
+```console
+python -m unittest discover -s tests   # 80+ tests, stdlib only, no extras
+grounded scan src                      # self-scan gate, must report clean
+grounded scan examples/v2demo          # fixture tree, expect 10 findings
+```
+
+## Contributing
+
+Issues and pull requests are welcome. Please include:
+
+- a minimal fixture (a few lines showing the comment and the code),
+- current output vs expected output,
+- the checker id in the issue title.
+
+New checkers are accepted only with a fixture, tests, and no new runtime
+dependencies (stdlib only is a project rule).
+
+## License
+
+MIT. See [LICENSE](LICENSE).