Skip to content

Commit 216c503

Browse files
denisecasedenisecase
committed
add specs
1 parent cefaa8f commit 216c503

10 files changed

Lines changed: 414 additions & 124 deletions

File tree

‎.editorconfig‎

Lines changed: 45 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,14 @@
11
# REQ.UNIVERSAL: All professional GitHub project repositories MUST include .editorconfig.
2-
# WHY: Establish a cross-editor baseline (VS Code, PyCharm, Vim, etc.) so diffs stay clean and formatting is consistent.
3-
# ALT: Repository may omit .editorconfig ONLY if formatting is enforced equivalently by CI + formatter tooling.
2+
# WHY: Establish a cross-editor baseline so diffs stay clean and formatting is consistent.
3+
# ALT: Repository may omit .editorconfig ONLY if formatting is enforced equivalently by CI and formatter tooling.
44
# CUSTOM: Adjust indent_size defaults only if organizational standards change; keep stable across projects.
5+
# NOTE: Sections are ordered by editorial importance, not strict alphabetical order.
6+
# EditorConfig is documented at https://editorconfig.org
57

8+
[*.{editorconfig}]
69
root = true
710

8-
# === Global defaults ===
11+
# === Global defaults (always apply) ===
912

1013
[*]
1114
# WHY: Normalize line endings and encoding across Windows, macOS, and Linux.
@@ -22,7 +25,27 @@ trim_trailing_whitespace = true
2225
indent_style = space
2326
indent_size = 2
2427

25-
# === Markup ===
28+
29+
# === Build systems (special rules) ===
30+
31+
[Makefile]
32+
# WHY: Makefiles require tabs.
33+
indent_style = tab
34+
35+
[*.mk]
36+
# WHY: Makefile includes require tabs.
37+
indent_style = tab
38+
39+
40+
# === Citation and metadata ===
41+
42+
[CITATION.cff]
43+
# WHY: Citation tooling expects stable YAML formatting.
44+
indent_size = 2
45+
indent_style = space
46+
47+
48+
# === Markup and documentation ===
2649

2750
[*.md]
2851
# WHY: Keep Markdown clean; use explicit <br> for hard line breaks.
@@ -44,7 +67,8 @@ indent_style = space
4467
indent_size = 2
4568
indent_style = space
4669

47-
# === Data and config ===
70+
71+
# === Data and configuration ===
4872

4973
[*.{json,jsonc,jsonl,ndjson}]
5074
# WHY: JSON tooling typically expects 2 spaces.
@@ -56,7 +80,8 @@ indent_style = space
5680
indent_size = 4
5781
indent_style = space
5882

59-
# === Code ===
83+
84+
# === Programming languages ===
6085

6186
[*.{js,ts}]
6287
# WHY: JS/TS ecosystem commonly uses 2 spaces.
@@ -74,11 +99,24 @@ indent_size = 4
7499
indent_style = space
75100

76101
[*.{c,cpp,h,java,cs,go,rs}]
77-
# WHY: Many C-family and systems languages commonly use 4 spaces (project-dependent).
102+
# WHY: Many C-family and systems languages commonly use 4 spaces.
78103
indent_size = 4
79104
indent_style = space
80105

81106
[*.{sh,bash}]
82107
# WHY: Shell script convention is 2 spaces.
83108
indent_size = 2
84109
indent_style = space
110+
111+
112+
# === Proof assistants and formal languages ===
113+
114+
[*.lean]
115+
# WHY: Lean 4 convention is 2 spaces; matches Mathlib and stdlib style.
116+
indent_size = 2
117+
indent_style = space
118+
119+
[*.{v,vo}]
120+
# WHY: Coq convention is 2 spaces.
121+
indent_size = 2
122+
indent_style = space

‎.github/dependabot.yml‎

Lines changed: 14 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,21 @@
1-
# .github/dependabot.yml
1+
# REQ.PROJECT: This repository SHOULD track GitHub Actions updates automatically.
2+
# WHY: GitHub Actions are executable dependencies and may receive security or behavior updates.
3+
# OBS: This repository has no language-level dependencies (Python, JS, Rust, etc.).
4+
# OBS: GitHub Actions are the only dependency class currently in scope.
5+
# ALT: Dependabot could be omitted if workflows are pinned and reviewed manually.
6+
# CUSTOM: Update interval if CI cadence or security posture changes.
7+
28
version: 2
9+
310
updates:
411
- package-ecosystem: "github-actions"
512
directory: "/"
13+
14+
# WHY: Monthly cadence balances stability with security updates.
15+
# ALT: Use "weekly" for higher-security environments.
616
schedule:
717
interval: "monthly"
18+
19+
# WHY: Clear commit prefix simplifies changelog review and filtering.
820
commit-message:
9-
prefix: "(deps)"
21+
prefix: "(deps)"

‎.github/workflows/ci.yml‎

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
# WHY-FILE: Minimal checks for specification repositories.
2+
# REQ: Any check that can be run locally MUST be available locally via pre-commit.
3+
# REQ: CI MUST NOT introduce arbitrary rules that are not reproducible locally.
4+
# OBS: CI does not introduce additional style rules beyond repo configuration.
5+
6+
name: CI
7+
8+
on:
9+
pull_request:
10+
push:
11+
branches: [main]
12+
workflow_dispatch:
13+
14+
jobs:
15+
hygiene:
16+
name: Repository checks
17+
runs-on: ubuntu-latest
18+
19+
permissions:
20+
contents: read
21+
22+
steps:
23+
- name: 1) Checkout repository code
24+
# WHY: Needed to access files for checks.
25+
uses: actions/checkout@v6
26+
27+
- name: 2) Run pre-commit (all files)
28+
# WHY: Single source of truth for locally runnable quality gates.
29+
# OBS: Fails if hooks would modify files; does not commit changes.
30+
uses: pre-commit/action@v3.0.1
31+
with:
32+
extra_args: --all-files

‎.github/workflows/links.yml‎

Lines changed: 35 additions & 39 deletions
Original file line numberDiff line numberDiff line change
@@ -1,46 +1,40 @@
1-
# WHY: Automated link checking - behavior controlled by repo variable
2-
# OBS: Set IS_ACTIVE_REPO=true in GitHub Repository Settings > Secrets and variables > Actions > Variables
3-
# ALT: Default (no variable set) runs manual only - perfect for student repos
1+
# WHY-FILE: Automated link checking.
2+
# OBS: Behavior is configured in lychee.toml in this repository.
3+
# OBS: Runs on pull requests and monthly on schedule; manual trigger always available.
44

55
name: Check Links
66

77
on:
88
workflow_dispatch: # WHY: Manual trigger - always available
99

10-
schedule:
11-
- cron: "0 6 1 * *" # WHY: Runs monthly (1st of month) if IS_ACTIVE_REPO=true
10+
pull_request: # WHY: Validates PR links before merge
1211

13-
pull_request: # WHY: Validates PR links if IS_ACTIVE_REPO=true
12+
schedule:
13+
- cron: "0 6 1 * *" # WHY: Runs monthly (1st of month)
1414

15-
# WHY: Prevent multiple simultaneous link checks on same ref
1615
concurrency:
16+
# WHY: Prevent multiple simultaneous link checks on same ref
1717
group: link-check-${{ github.ref }}
1818
cancel-in-progress: true
1919

2020
jobs:
2121
lychee:
22-
# WHY: Skip scheduled/PR runs unless IS_ACTIVE_REPO=true or manual trigger
23-
# OBS: vars.IS_ACTIVE_REPO linted as error in VS Code but works on GitHub
24-
if: github.event_name == 'workflow_dispatch' || vars.IS_ACTIVE_REPO == 'true'
25-
2622
runs-on: ubuntu-latest
2723

28-
# WHY: Permissions needed for PR comments and issue creation
2924
permissions:
3025
contents: read
3126
issues: write
3227
pull-requests: write
3328

3429
steps:
35-
- uses: actions/checkout@v6 # OBS: v6 current as of Dec 2025
30+
- name: 1) Checkout repository code
31+
uses: actions/checkout@v6 # OBS: v6 current as of Dec 2025
3632

37-
# WHY: Check all documentation and config files for broken links
38-
- name: Check links with Lychee
39-
uses: lycheeverse/lychee-action@v2 # OBS: v2 current as of Dec 2025
33+
- name: 2) Check links with Lychee
34+
uses: lycheeverse/lychee-action@v2
4035
with:
4136
args: >
42-
--verbose
43-
--no-progress
37+
--config lychee.toml
4438
--user-agent "${{ github.repository }}/lychee"
4539
'./**/*.bib'
4640
'./**/*.md'
@@ -52,47 +46,49 @@ jobs:
5246
env:
5347
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
5448

55-
# WHY: Provide helpful feedback on PRs with broken links
56-
- name: Comment on PR if links broken
49+
- name: 3) Comment on PR if links broken
5750
if: failure() && github.event_name == 'pull_request'
58-
uses: actions/github-script@v8 # OBS: v8 current as of Dec 2025
51+
uses: actions/github-script@v8
5952
with:
6053
script: |
61-
const comment = `## Link Check Results
62-
63-
Some links appear broken. Check the [workflow logs](${context.payload.repository.html_url}/actions/runs/${context.runId}) for details.`;
64-
65-
github.rest.issues.createComment({
54+
const runUrl = `${context.payload.repository.html_url}/actions/runs/${context.runId}`;
55+
const comment = [
56+
"## Link Check Results",
57+
"",
58+
`Some links appear broken. Check the workflow logs: ${runUrl}`,
59+
].join("\n");
60+
61+
await github.rest.issues.createComment({
6662
issue_number: context.issue.number,
6763
owner: context.repo.owner,
6864
repo: context.repo.repo,
69-
body: comment
65+
body: comment,
7066
});
7167
72-
# WHY: Track broken links found during scheduled checks
73-
# OBS: Only creates issue if none already open with 'broken-links' label
74-
- name: Create issue for scheduled failures
68+
- name: 4) Create issue for scheduled failures # WHY: Track broken links found during scheduled checks
69+
# OBS: Only creates issue if none already open with 'broken-links' label
7570
if: failure() && github.event_name == 'schedule'
76-
uses: actions/github-script@v8 # OBS: v8 current as of Dec 2025
71+
uses: actions/github-script@v8
7772
with:
7873
script: |
79-
const title = `Link Check Failed - ${new Date().toISOString().split('T')[0]}`;
80-
const body = `Weekly link check found broken links. [Check logs](${context.payload.repository.html_url}/actions/runs/${context.runId})`;
74+
const date = new Date().toISOString().split("T")[0];
75+
const title = `Link Check Failed - ${date}`;
76+
const runUrl = `${context.payload.repository.html_url}/actions/runs/${context.runId}`;
77+
const body = `Monthly link check found broken links.\n\nWorkflow logs: ${runUrl}`;
8178
82-
// WHY: Avoid duplicate issues
8379
const existing = await github.rest.issues.listForRepo({
8480
owner: context.repo.owner,
8581
repo: context.repo.repo,
86-
labels: 'broken-links',
87-
state: 'open'
82+
labels: "broken-links",
83+
state: "open",
8884
});
8985
9086
if (existing.data.length === 0) {
9187
await github.rest.issues.create({
9288
owner: context.repo.owner,
9389
repo: context.repo.repo,
94-
title: title,
95-
body: body,
96-
labels: ['maintenance', 'broken-links']
90+
title,
91+
body,
92+
labels: ["maintenance", "broken-links"],
9793
});
9894
}

‎.gitignore‎

Lines changed: 32 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1,13 +1,38 @@
1-
# WHY-FILE: Org governance repo - ignore only OS/editor artifacts.
1+
# REQ.UNIVERSAL: Spec repositories MUST ignore editor, OS, and transient artifacts.
2+
# WHY: Prevent accidental commits of local or generated noise.
3+
# ALT: Expand only if the repository adds tooling that generates artifacts.
24

3-
# === OS ===
5+
# === OS artifacts ===
46
.DS_Store
57
Thumbs.db
6-
desktop.ini
78

8-
# === Editors / IDEs ===
9-
.vscode/
10-
.idea/
11-
*.code-workspace
9+
# === Editor artifacts ===
1210
*.swp
1311
*.swo
12+
*.bak
13+
*~
14+
.vscode/
15+
.idea/
16+
17+
# === Temporary files ===
18+
.tmp/
19+
.temp/
20+
21+
# === LaTeX build artifacts (if SPEC is rendered locally) ===
22+
*.aux
23+
*.bbl
24+
*.blg
25+
*.log
26+
*.out
27+
*.toc
28+
*.fls
29+
*.fdb_latexmk
30+
31+
# === PDF previews ===
32+
*.pdf
33+
34+
# === Proof assistant artifacts (defensive, non-binding) ===
35+
*.olean
36+
*.ilean
37+
*.trace
38+
.lake/

‎.pre-commit-config.yaml‎

Lines changed: 67 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,67 @@
1+
# REQ.PROJECT: This repository SHOULD include a .pre-commit-config.yaml when quality gates are required.# REQ: Any check that can be run locally MUST be available here.# WHY: Provide fast, consistent local checks aligned with upstream quality gates.# WHY: Keep local checks compatible with repository-wide formatting rules.# OBS: Formatting baselines are defined in# .editorconfig (whitespace/indentation) and# .gitattributes (EOL normalization).# OBS: These hooks do not override .editorconfig or .gitattributes;# they only prevent common diff noise and validate repository metadata.# ALT: Checks that are inherently non-local are handled upstream.# CUSTOM: Keep the hook set minimal and non-destructive for normative Markdown specs.## OPTIONAL LOCAL USAGE (no repo venv required):# Install uv (once, user-level).# uv self update# uvx pre-commit install# uvx pre-commit run --all-files## OBS: If a hook reports "files were modified", re-run last command to confirm a clean pass.## NOTE: pre-commit is optional.# Repositories do not require Python, uv, or pre-commit to clone or commit.exclude: | (?x)^( \.DS_Store| \.ipynb_checkpoints/| \.mypy_cache/| \.pytest_cache/| \.ruff_cache/| \.tox/| \.venv/| build/| dist/| node_modules/| site/ )repos: - repo: https://github.com/pre-commit/pre-commit-hooks rev: v6.0.0 # OBS: v6 current as of Dec 30 2025 hooks: - id: check-added-large-files # OBS: prevent large binary files - id: trailing-whitespace # OBS: clean trailing whitespace per .editorconfig - id: end-of-file-fixer # OBS: ensure files end with a newline per .gitattributes - id: check-merge-conflict # OBS: prevent committing unresolved merge conflicts # WHY: Workflow files may intentionally include marker-like strings (e.g., >>>>). exclude: ^\.github/workflows/.*\.(yml|yaml)$ - id: check-yaml # OBS: validate YAML syntax files: \.(yml|yaml)$ - repo: https://github.com/adrienverge/yamllint rev: v1.37.1 # OBS: pinned for reproducibility hooks: - id: yamllint # OBS: validate YAML structure and policy (no line-length enforcement) args: [-c, .yamllint.yml] files: \.(yml|yaml)$ - repo: https://github.com/rhysd/actionlint rev: v1.7.10 # OBS: v1.7.10 current as of Dec 30 2025 hooks: - id: actionlint # OBS: validate GitHub Actions workflow syntax files: ^\.github/workflows/.*\.(yml|yaml)$# REQ.PROJECT: This repository SHOULD include a .pre-commit-config.yaml when quality gates are required.
2+
# REQ: Any check that can be run locally MUST be available here.
3+
# WHY: Provide fast, consistent local checks aligned with upstream quality gates.
4+
# WHY: Keep local checks compatible with repository-wide formatting rules.
5+
# OBS: Formatting baselines are defined in
6+
# .editorconfig (whitespace/indentation) and
7+
# .gitattributes (EOL normalization).
8+
# OBS: These hooks do not override .editorconfig or .gitattributes;
9+
# they only prevent common diff noise and validate repository metadata.
10+
# ALT: Checks that are inherently non-local are handled upstream.
11+
# CUSTOM: Keep the hook set minimal and non-destructive for normative Markdown specs.
12+
#
13+
# OPTIONAL LOCAL USAGE (no repo venv required):
14+
# Install uv (once, user-level).
15+
# uv self update
16+
# uvx pre-commit install
17+
# uvx pre-commit run --all-files
18+
#
19+
# OBS: If a hook reports "files were modified", re-run last command to confirm a clean pass.
20+
#
21+
# NOTE: pre-commit is optional.
22+
# Repositories do not require Python, uv, or pre-commit to clone or commit.
23+
24+
exclude: |
25+
(?x)^(
26+
\.DS_Store|
27+
\.ipynb_checkpoints/|
28+
\.mypy_cache/|
29+
\.pytest_cache/|
30+
\.ruff_cache/|
31+
\.tox/|
32+
\.venv/|
33+
build/|
34+
dist/|
35+
node_modules/|
36+
site/
37+
)
38+
39+
repos:
40+
- repo: https://github.com/pre-commit/pre-commit-hooks
41+
rev: v6.0.0
42+
hooks:
43+
- id: check-added-large-files # OBS: prevent large binary files
44+
- id: trailing-whitespace # OBS: clean trailing whitespace per .editorconfig
45+
- id: end-of-file-fixer # OBS: ensure files end with a newline per .gitattributes
46+
47+
- id: mixed-line-ending # OBS: normalize line endings before linters run
48+
# WHY: yamllint enforces LF; Windows working copies may be CRLF.
49+
args: [--fix=lf]
50+
51+
- id: check-merge-conflict # OBS: prevent committing unresolved merge conflicts
52+
53+
- id: check-yaml # OBS: validate YAML syntax
54+
files: \.(yml|yaml)$
55+
56+
- repo: https://github.com/adrienverge/yamllint
57+
rev: v1.37.1
58+
hooks:
59+
- id: yamllint # OBS: validate YAML structure and policy (no line-length enforcement)
60+
args: [-c, .yamllint.yml]
61+
files: \.(yml|yaml)$
62+
63+
- repo: https://github.com/rhysd/actionlint
64+
rev: v1.7.10
65+
hooks:
66+
- id: actionlint # OBS: validate GitHub Actions workflow syntax
67+
files: ^\.github/workflows/.*\.(yml|yaml)$

0 commit comments

Comments
 (0)