circa-ci 0.2.2__tar.gz

circa_ci-0.2.2/.gitignore

@@ -0,0 +1,29 @@
+# Python
+__pycache__/
+*.py[cod]
+*.so
+.Python
+.venv/
+venv/
+env/
+
+# Tooling
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+coverage.xml
+htmlcov/
+
+# Packaging
+build/
+dist/
+*.egg-info/
+
+# Editors and OS
+.DS_Store
+.idea/
+.vscode/
+
+# Local real-log pilots (never commit real logs)
+pilot/

circa_ci-0.2.2/CHANGELOG.md

@@ -0,0 +1,187 @@
+# Changelog
+
+All notable changes to CIRCA are listed here. Versions follow
+[Semantic Versioning](https://semver.org); while CIRCA is below 1.0, a minor
+version may change behavior.
+
+## 0.2.2 — 2026-11-01
+
+Packaging only; analysis behavior is unchanged.
+
+- Prepared for PyPI as `circa-ci`, because the name `circa` belongs to an
+  unrelated project. The command (`circa`) and the import name (`circa`) are
+  unchanged. If an earlier version is installed, run `pip uninstall circa`
+  before installing 0.2.2; removing it afterwards also removes the `circa`
+  command.
+- Added a manually run publishing workflow that uses PyPI trusted publishing
+  (no stored API token). It publishes only a tag that matches the package
+  version, to TestPyPI or, through the `pypi` environment, to PyPI.
+- The source distribution no longer includes the team knowledge file, tests,
+  evaluation dataset, agent instructions, or CI configuration. The build
+  backend is pinned.
+- README links to CONTRIBUTING, SECURITY, and CHANGELOG are absolute, so they
+  work on the PyPI project page.
+
+## 0.2.1 — 2026-11-01
+
+### Security
+
+- Fixed partial redaction of URL passwords that contain `@`. In v0.2.0,
+  `https://deploy:pass@word@host/` became `https://deploy:[REDACTED]@word@host/`,
+  leaving the part of the password after its first `@` in analysis,
+  fingerprints, LLM prompts, terminal and JSON output, and `pending_review`
+  drafts that `investigate-log` saved to a knowledge file. The whole password is
+  now redacted, up to the last `@` before the host. URL passwords without `@`
+  were fully redacted in v0.2.0 too.
+- Output already produced by v0.2.0 is not repaired automatically. If a CI log
+  you processed with v0.2.0 had a URL password containing `@`, treat that
+  password as exposed and rotate it. To find saved drafts with a leftover, run
+  `grep -cE '\[REDACTED\]@[^ /?#"]*@' path/to/incidents.json` (any count above
+  0), then edit those values to `[REDACTED]` as described in
+  [SECURITY.md](SECURITY.md#repairing-a-knowledge-file). Saved reports and
+  copied terminal output need the same review.
+- Dedup fingerprints change only for logs that contain such URLs.
+
+## 0.2.0 — 2026-11-01
+
+Changes since v0.1.0 (2026-10-22). CIRCA is still local-first: analysis is
+deterministic and works without any AI service, and the only runtime Python
+dependencies are Pydantic and Typer.
+
+### Investigation workflow
+
+- New `circa investigate-log` command. It runs the full workflow on one log:
+  deterministic analysis, then verified team incidents (a strong match with a
+  validated fix is returned as a known solution with no LLM call), then
+  already-recorded failures, and only then at most one call to an optional
+  local Ollama model.
+- A useful LLM diagnosis is saved as a `pending_review` draft. A draft needs a
+  category, a root cause grounded in the log, and at least one quoted log line.
+  Suggestions that would weaken a safeguard (disable, skip, bypass, `--force`,
+  thresholds, baselines) are left out and named in a note.
+- The deterministic category stays authoritative; the LLM category is used
+  only when the analyzer found none, and `draft_origin.category_source` records
+  where it came from.
+
+### GitHub Actions
+
+- New `circa runs` command lists a repository's recent failed runs through the
+  GitHub CLI (`gh`).
+- `investigate-log` accepts a run URL, a run ID (with `--repo` or a detected
+  repository), or no source, in which case it lists failed runs and asks you to
+  choose one.
+- The repository is detected from the checkout's github.com remotes. CIRCA
+  stops instead of guessing when remotes disagree, and never prints remote
+  URLs, which can contain credentials. CIRCA never reads the `gh` token.
+
+### Team knowledge and human review
+
+- Team incident knowledge lives in a JSON file passed explicitly with
+  `--knowledge`, for example `team/incidents.json`.
+- New `circa knowledge` commands: `add`, `update`, `verify`, `reject`,
+  `supersede`, `show`, `list`, and `validate`.
+- Lifecycle: `pending_review` → `verified` → `superseded`, or `rejected`. Only
+  `verified` incidents are matched. Every write shows the record, asks for
+  confirmation (or `--yes`), writes atomically, and refuses if the file changed
+  since it was read.
+- A real incident can be verified only with a root cause, a reviewer, and a fix
+  validated by a named method with evidence. LLM output and a single
+  successful retry never validate a fix.
+- Exact duplicates (same dedup fingerprint) are rejected; near duplicates need
+  `--allow-similar`.
+
+### Setup and first-time use
+
+- New `circa doctor` (read-only prerequisite checks) and `circa init` (creates
+  an empty knowledge file only if it does not exist).
+- New `circa --version`.
+- Rewritten README with a quick start, tutorial, and troubleshooting table.
+
+### Deterministic analysis
+
+- Performance-threshold assessment for logs with an explicit threshold
+  violation. It reports a candidate cause as a hypothesis, never changes
+  thresholds, and does not change the category.
+- Errors are matched line by line in pipeline-stage order, so the earliest
+  failing stage wins. Informational lines and printed source code (diffs,
+  Bandit snippets) are not treated as errors.
+- A historical root cause is reused only when its pipeline stage fits the
+  failure.
+- Newly recognized failures: `npm ERR!`, Ruff lint and format, Prettier, mypy,
+  Bandit findings, C/C++ compiler errors, and Python `SyntaxError`,
+  `IndentationError`, and `TabError`. File, line, and rule details are reported
+  when the log states them.
+
+### Evaluation
+
+- New `circa evaluate` measures deterministic classification and root-cause
+  correctness on labeled cases (`evaluation/cases.json`, including sanitized
+  real CI logs) plus the 35 legacy benchmark cases. It is read-only and never
+  reads team knowledge.
+- On the shipped dataset, category accuracy is 48/60 confirmed cases with no
+  false positives; the legacy set stays at 27/35. These numbers describe
+  CIRCA's own labeled cases, not production accuracy.
+- The retrieval benchmark (`circa benchmark`) and its synthetic dataset are
+  unchanged.
+
+### Security
+
+- Credentials are redacted before any processing. Recognized values become
+  `[REDACTED]` while the rest of the message is kept. This covers GitHub,
+  GitLab, Slack, npm, PyPI, Google, and OpenAI/Anthropic-style tokens; AWS
+  access key IDs; JSON Web Tokens; `Authorization` and bearer values; passwords
+  in URLs; credential options and assignments (such as `NPM_TOKEN=...`); and PEM
+  private keys.
+- Fingerprints, analysis, LLM prompts, drafts, and terminal and JSON output all
+  use the redacted text. Fingerprints of logs without credentials are
+  unchanged.
+- Redaction fails closed: if it cannot complete, the command stops with a safe
+  error before anything reads the log.
+- Credentials in LLM output are redacted and block the draft. Credentials in a
+  draft's source name or model setting are redacted.
+- Knowledge records containing a recognized credential are rejected in every
+  text field, including `draft_origin.cited_log_lines`. The error names the
+  field (for example `evidence[1]`) but never the value.
+- Terminal control sequences in CI logs and GitHub output are removed before
+  display. Invalid `circa analyze` input reports field errors without quoting
+  values, and tracebacks never show local variables.
+- CI quality gate: Prettier, Ruff, tests on Python 3.12 and 3.13 with a 90%
+  coverage floor, mypy, Bandit, pip-audit, Gitleaks, actionlint, zizmor, and a
+  wheel install smoke test. Actions are pinned to commit SHAs with read-only
+  permissions.
+
+### Upgrade notes
+
+- **Knowledge files may need a one-time repair.** Credential detection is
+  broader than in v0.1.0, so a team file that loaded before can now fail with
+  `incident text matches a secret or credential pattern in <field>`. Replace
+  the named value with `[REDACTED]` and run `circa knowledge validate`. See
+  [SECURITY.md](SECURITY.md#repairing-a-knowledge-file). Records are never
+  changed or deleted automatically.
+- Lines containing credentials are now kept in redacted form instead of being
+  dropped from investigation evidence. Dedup fingerprints change only for such
+  logs.
+- The redaction placeholder is `[REDACTED]`. Text already masked as `***` or
+  `<redacted>` is still accepted.
+
+### Known limitations
+
+- Classification is rule- and keyword-based. Failures outside the recognized
+  signatures are reported as `unknown`, and only one explicit failure kind is
+  named per log.
+- Credential detection is pattern-based, not complete (see
+  [SECURITY.md](SECURITY.md)).
+- GitHub support is limited to github.com through the GitHub CLI. GitHub
+  Enterprise and other CI systems are not supported.
+- The LLM path needs a local Ollama server; small local models give variable
+  hypotheses, which is why every draft requires human review.
+- `circa evaluate` needs a repository checkout; its dataset is not in the
+  wheel.
+
+## 0.1.0 — 2026-10-22
+
+First release: deterministic failure analysis of structured failures
+(`circa analyze`) and raw logs (`circa analyze-log`), packaged synthetic
+historical incidents, keyword retrieval with optional local semantic retrieval,
+optional local LLM explanation and classification, and the retrieval benchmark
+(`circa benchmark`).

circa_ci-0.2.2/CONTRIBUTING.md

@@ -0,0 +1,99 @@
+# Contributing to CIRCA
+
+Thank you for helping improve CIRCA. This guide covers setting up a
+development environment, running the checks CI runs, and what a pull request
+needs.
+
+## Development setup
+
+Requirements: Python 3.12 or 3.13, and Git. Node.js (for Prettier) and the
+standalone `actionlint` and `gitleaks` tools are needed only to reproduce every
+CI check locally.
+
+```bash
+git clone https://github.com/scmbuildrelease/CIRCA.git && cd CIRCA
+python3 -m venv .venv && . .venv/bin/activate
+python -m pip install -e ".[dev]"
+circa --version
+```
+
+The `dev` extra installs pytest, pytest-cov, and pinned versions of Ruff and
+mypy. Ollama and the GitHub CLI are not needed for development: tests use fakes
+and never call a model, GitHub, or the network.
+
+## Tests and quality checks
+
+Run these before opening a pull request. They match the CI jobs in
+`.github/workflows/ci.yml`.
+
+```bash
+python -m pytest --cov --cov-report=term-missing   # fails below 90% coverage
+ruff check .
+ruff format --check .
+mypy
+npx --yes prettier@3.9.9 --check "**/*.{md,yml,yaml,json}"
+pipx run bandit==1.9.4 -c pyproject.toml -r src
+pipx run pip-audit==2.10.1 --strict .
+pipx run zizmor==1.30.1 .github/workflows
+actionlint
+gitleaks git --redact .
+python -m pip install build==1.6.1 && python -m build   # sdist and wheel in dist/
+```
+
+CI runs the tests on Python 3.12 and 3.13. CI only reports problems; it never
+formats or fixes files. Run `ruff format .` and
+`npx prettier@3.9.9 --write <files>` yourself.
+
+Two read-only regression checks are useful when you change analysis code.
+Report any change in their output in your pull request:
+
+```bash
+circa evaluate     # deterministic classification on evaluation/cases.json
+circa benchmark    # retrieval on the packaged synthetic dataset
+```
+
+## Project principles
+
+These come from [AGENTS.md](AGENTS.md); please follow them in every change.
+
+- **Deterministic analysis is the primary authority.** It must work without any
+  LLM. The LLM is optional, local (Ollama), and never replaces or overrides a
+  deterministic result.
+- **Keep dependencies minimal.** The runtime depends only on Pydantic and
+  Typer. Do not add a dependency, external service, or large framework without
+  discussing it in an issue first.
+- **Keep changes small and focused.** Reuse existing code before adding
+  abstractions, and change only what the pull request is about.
+- **Add tests for new behavior,** including negative cases (what must _not_ be
+  recognized), and run the full suite.
+- **Do not tune rules to evaluation labels.** Add evaluation cases when a real
+  failure is understood, not to make a metric go up.
+
+## Data and security rules
+
+- **Never commit real credentials, private CI logs, or customer data.** Test
+  fixtures use synthetic values. Assemble credential-shaped test strings at
+  runtime (for example `"ghp" + "_" + ...`) so Gitleaks does not flag them.
+- **Packaged incidents and evaluation data are read-only and synthetic.** Real
+  logs under `evaluation/logs/` must be sanitized.
+- **Do not edit `team/incidents.json` by hand in a feature pull request.**
+  Changes to team knowledge go through the `circa knowledge` commands and human
+  review.
+- **Never mark a fix `validated` without real validation evidence.** LLM output
+  and a single successful retry are not validation.
+- Report vulnerabilities privately as described in [SECURITY.md](SECURITY.md).
+
+## Pull requests
+
+- Open an issue first for anything beyond a small fix, so the approach can be
+  agreed on.
+- Describe what changed and why, and how you tested it. Include `circa evaluate`
+  or `circa benchmark` differences if analysis behavior changed.
+- Keep CLI and JSON output backward compatible unless the change is the point of
+  the pull request; call out any change explicitly.
+- Update `README.md` and `CHANGELOG.md` (under the unreleased version) when user
+  visible behavior changes.
+- All CI checks must pass before merging.
+
+By contributing, you agree that your contribution is licensed under the
+[Apache License 2.0](LICENSE).

circa_ci-0.2.2/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.