diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS new file mode 100644 index 0000000..4ea21a5 --- /dev/null +++ b/.github/CODEOWNERS @@ -0,0 +1,14 @@ +# CODEOWNERS +# Each line maps a path pattern to one or more GitHub usernames or teams. +# The last matching rule takes precedence. +# See: https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-code-owners + +# Default owners for everything in the repository +* @nitrocode + +# Core logic and tests require extra scrutiny +death-clock-core.js @nitrocode +tests/ @nitrocode + +# Deployment and CI configuration +.github/ @nitrocode diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..52f74f6 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,65 @@ +# Contributing to AI Death Clock + +Thank you for your interest in contributing! Please read this guide before opening a pull request. + +--- + +## Getting Started + +1. Fork the repository and create a feature branch from `main`. +2. Install dev dependencies: `npm ci` +3. Run tests before making changes to establish a baseline: `npm test` + +--- + +## Coding Conventions + +| Rule | Detail | +|------|--------| +| **Core / DOM split** | `death-clock-core.js` must never reference the DOM. All DOM work goes in `script.js`. | +| **No runtime dependencies** | Do not add npm runtime packages. The site must remain fully static. | +| **CommonJS + browser export** | `death-clock-core.js` exports via `module.exports` for Jest and `window.DeathClockCore` for the browser. Keep both in sync. | +| **HTML escaping** | All dynamic strings rendered into `innerHTML` must pass through `escHtml()`. Never assign untrusted data directly to `innerHTML`. | +| **Constants consistency** | When updating `BASE_TOKENS`, `TOKENS_PER_SECOND`, or `BASE_DATE_ISO`, always update all three together with a comment citing the source. | +| **Tests for new functions** | Every new pure function added to `death-clock-core.js` must have corresponding unit tests in `tests/death-clock.test.js`. | + +--- + +## Pull Request Checklist + +Before requesting a review, confirm all of the following: + +- [ ] Tests pass locally: `npm run test:ci` +- [ ] Coverage has not dropped below the thresholds (80 % lines/functions, 70 % branches) +- [ ] No DOM references introduced in `death-clock-core.js` +- [ ] No new runtime npm packages added +- [ ] All dynamic `innerHTML` values are escaped through `escHtml()` +- [ ] If data constants were changed, all three (`BASE_TOKENS`, `TOKENS_PER_SECOND`, `BASE_DATE_ISO`) were updated together with a source comment +- [ ] New pure functions are exported from `DeathClockCore` and imported in `script.js` +- [ ] Commit messages are concise and descriptive + +--- + +## Running Tests + +```bash +npm ci # install dev dependencies +npm test # jest --coverage (interactive) +npm run test:ci # jest --ci --coverage (strict; fails on coverage drop) +``` + +--- + +## Reporting Bugs + +Open a GitHub Issue with: +- A clear title and description +- Steps to reproduce +- Expected vs. actual behaviour +- Browser and OS version if relevant + +--- + +## Questions + +Open a GitHub Discussion or an Issue tagged `question`. diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..bc06bee --- /dev/null +++ b/LICENSE @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2026 RB + +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. diff --git a/README.md b/README.md index 60edaa9..da08178 100644 --- a/README.md +++ b/README.md @@ -2,7 +2,7 @@ > **Live site:** `https://nitrocode.github.io/token-deathclock/` -A GitHub Pages visualisation that shows the environmental cost of global AI token consumption — featuring live counters, milestone tracker, token-growth chart with projections, and a prompt/PR scoring section. +A GitHub Pages visualisation that shows the environmental cost of global AI token consumption — featuring live counters, milestone tracker, and a token-growth chart with projections. Created by **RB**. @@ -18,7 +18,6 @@ Created by **RB**. | **Growth chart** | Historical data + 18-month projection on a log scale (Chart.js) | | **Predictions table** | Predicted calendar dates for each milestone | | **Dark / Light mode** | Toggle button; dark mode is the default | -| **Prompt & PR scoring** | Collapsible section showing the rubric, recommendations, and score improvement | --- @@ -61,35 +60,6 @@ Tests are in `tests/death-clock.test.js` and cover all pure functions in `death- --- -## Prompt & PR Score - -| | Score | -|---|---| -| **Prompt (initial)** | 74 / 100 | -| **Prompt (after recommendations)** | 94 / 100 | - -### Recommendations addressed - -| Recommendation | Impact | Status | -|---|---|---| -| Define "life essential" categories explicitly | +2 pts | ✅ Done | -| Specify exact token thresholds for each milestone | +4 pts | ✅ Done | -| Define preferred charting library (Chart.js) | +2 pts | ✅ Done | -| Cite data sources for environmental correlations | +2 pts | ✅ Done | -| Specify test framework (Jest) | +3 pts | ✅ Done | -| Include GitHub Pages deployment configuration | +4 pts | ✅ Done | -| Specify responsive-design requirements | +3 pts | ✅ Done | -| Define visual style | +1 pt | ✅ Done | - -### Recommendations not yet addressed - -| Recommendation | Impact | -|---|---| -| Specify minimum test-coverage percentage | +3 pts | -| List specific test scenarios in prompt | +2 pts | - ---- - ## Architecture ``` @@ -144,10 +114,10 @@ Tests are in `tests/death-clock.test.js` and cover all pure functions in `death- - [x] **Fix total-counter anchor** — `getCurrentTokens()` now uses `BASE_DATE_ISO` so the counter reflects true elapsed time since the data anchor, not since the page was loaded. #### Priority 2 — Community & compliance -- [ ] Add a `LICENSE` file (MIT or Apache-2.0 recommended). -- [ ] Add `CONTRIBUTING.md` with a pull-request checklist and coding conventions. -- [ ] Add `SECURITY.md` with a vulnerability-disclosure policy. -- [ ] Add a `CODEOWNERS` file to set review requirements. +- [x] Add a `LICENSE` file (MIT or Apache-2.0 recommended). +- [x] Add `CONTRIBUTING.md` with a pull-request checklist and coding conventions. +- [x] Add `SECURITY.md` with a vulnerability-disclosure policy. +- [x] Add a `CODEOWNERS` file to set review requirements. #### Priority 3 — Security hardening - [ ] Add a `Content-Security-Policy` meta tag in `index.html` to restrict inline scripts and limit allowed CDN origins (Chart.js, Google Fonts). diff --git a/SECURITY.md b/SECURITY.md new file mode 100644 index 0000000..5f0f10c --- /dev/null +++ b/SECURITY.md @@ -0,0 +1,46 @@ +# Security Policy + +## Supported Versions + +Only the latest version deployed at `https://nitrocode.github.io/token-deathclock/` is actively maintained. + +## Reporting a Vulnerability + +**Please do not report security vulnerabilities through public GitHub Issues.** + +To report a vulnerability, open a [GitHub Security Advisory](https://github.com/nitrocode/token-deathclock/security/advisories/new) in this repository. This keeps the details private until a fix is available. + +Include as much of the following information as possible: + +- Type of vulnerability (e.g. XSS, content injection, dependency with known CVE) +- The file(s) and line number(s) involved +- Step-by-step instructions to reproduce the issue +- Proof-of-concept code or screenshots (if applicable) +- Potential impact and attack scenario + +## Response Timeline + +| Step | Target | +|------|--------| +| Acknowledgement | Within 3 business days | +| Initial assessment | Within 7 business days | +| Fix or mitigation | Dependent on severity; critical issues targeted within 14 days | + +## Scope + +The following are in scope: + +- Cross-site scripting (XSS) in dynamically rendered HTML +- Dependency vulnerabilities in `package.json` devDependencies +- CDN resource integrity issues (Chart.js, Google Fonts) +- Sensitive data exposure + +The following are out of scope: + +- Issues in third-party CDN-hosted libraries that are not exploitable through this site +- Denial-of-service attacks against GitHub Pages infrastructure +- Social-engineering attacks + +## Preferred Languages + +Reports in English are preferred.