Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
27 changes: 27 additions & 0 deletions Tools/VBDocsGen/main.js

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

4 changes: 2 additions & 2 deletions Tools/VBDocsGen/main.js.map

Large diffs are not rendered by default.

58 changes: 58 additions & 0 deletions Tools/VBDocsGen/main.ts
Original file line number Diff line number Diff line change
Expand Up @@ -143,6 +143,9 @@ function groupBy<T>(

type IDocs = (IModule | IClass)[];
type IModule = {
ai?: string;
aiDate?: string;
aiDescription?: string;
name: string;
fileName: string;
description: string;
Expand Down Expand Up @@ -224,6 +227,9 @@ type ITagTypes =
| "TODO"
| "throws"
| "requires"
| "ai"
| "aidate"
| "aidesc"
| "static";

type ITagLine = {
Expand All @@ -245,6 +251,9 @@ type ICommentRecord =
| IDataTODO
| IDataThrows
| IDataRequires
| IDataAI
| IDataAIDate
| IDataAIDesc
| IDataStatic;

type IDataConstructor = {
Expand Down Expand Up @@ -307,6 +316,20 @@ type IDataRequires = {
tag: "requires";
data: string;
};
type IDataAI = {
tag: "ai";
data: string;
};

type IDataAIDate = {
tag: "aidate";
data: string;
};
type IDataAIDesc = {
tag: "aidesc";
data: string;
};

type IDataStatic = {
tag: "static";
};
Expand Down Expand Up @@ -416,6 +439,26 @@ function parseComment(comment: string): ICommentStore {
},
});
break;
case "ai":
if (!/^AI:[0RWX]$/.test(tagLine.content.trim())) {
throw new Error(`Invalid @ai mark: ${tagLine.content.trim()}`);
}
commentStore.push({ tag, data: tagLine.content.trim() });
break;
case "aidate": {
const value = tagLine.content.trim();
const date = new Date(value + "T00:00:00.000Z");
if (!/^\d{4}-\d{2}-\d{2}$/.test(value) ||
Number.isNaN(date.getTime()) || date.toISOString().slice(0, 10) !== value) {
throw new Error(`Invalid @aidate: ${value}`);
}
commentStore.push({ tag, data: value });
break;
}
case "aidesc":
if (!tagLine.content.trim()) throw new Error("Empty @aidesc");
commentStore.push({ tag, data: tagLine.content.trim() });
break;
case "example":
commentStore.push({ tag, data: tagLine.content.trim() });
break;
Expand Down Expand Up @@ -742,8 +785,23 @@ function parseModuleOrClass(
}
});

for (const tag of ["ai", "aidate", "aidesc"]) {
if (moduleDocsByTag[tag]?.length > 1) {
throw new Error(`Duplicate @${tag} in ${fileName}`);
}
}

//Build base module
let mod: IModule = {
...(moduleDocsByTag["ai"]?.length
? { ai: (moduleDocsByTag["ai"][0] as IDataAI).data }
: {}),
...(moduleDocsByTag["aidate"]?.length
? { aiDate: (moduleDocsByTag["aidate"][0] as IDataAIDate).data }
: {}),
...(moduleDocsByTag["aidesc"]?.length
? { aiDescription: (moduleDocsByTag["aidesc"][0] as IDataAIDesc).data }
: {}),
name: moduleName,
fileName,
description:
Expand Down
5 changes: 5 additions & 0 deletions changelog.md
Original file line number Diff line number Diff line change
Expand Up @@ -486,3 +486,8 @@ The 2025-2026 entries were audited retrospectively against commits through `1bcb
- 2026-11-01 `Tools/Testing` BREAKING - Remove the separate Tools/stdCallback-tests, stdDate-test, stdHTTP-tests, stdImage-tests stdWebSocket-tests and stdEnumerator-tests command folders. Maintainer scripts invoking those paths must migrate to `python Tools/Testing/run.py --suite <id>`: stdCallback.probes, stdDate, stdHTTP.local, stdImage stdWebSocket.local or stdEnumerator.local respectively. Image host selection is now `--host Excel` or `--host Word` through the shared command (formerly `--hosts`). Test bodies and specialized harnesses now live under tests/harnesses.

- 2026-11-10 `stdOutlook` FEATURE - Add a standalone Windows VBA7 class for classic Outlook identity, contacts, mail and calendar access through Extended MAPI, with plain-text/HTML email submission and Outlook Send/Receive synchronization. (#189)
- 2026-11-10 `contribution.md` DEV - Document module-level @ai, @aidate and @aidesc disclosures, first-evidenced dates, mixed provenance and named component classifications; explicit maintainer classifications supersede inference (#191).
- 2026-11-10 `src` NOTE - Add AI disclosures to all 94 source modules: the maintainer declares 73 previously unclassified modules AI:0 with the supplied description; the 21 reviewed classes retain their maintainer-confirmed classifications. Record AI:W overall with AI:X components for stdRegex/stdLambda native engines, stdReg additions and stdWindow subclassing thunks; identify stdEnumerator lazy traversal as manually reviewed. Preserve upstream credit and distinguish historical experiments from current code (#191).
- 2026-11-10 `Tools/VBDocsGen` DEV - Validate AI marks, ISO calendar dates, nonempty AI descriptions and duplicate module tags; expose optional ai, aiDate and aiDescription fields in docs.json without changing VBA APIs (#191).
- 2026-11-10 `docs/ai-provenance.json` DEV - Record all 94 source-module outcomes and searches across 43 Codex logs, 53 Cursor workspace records and 40 transcripts. Cross-check blame, dates and deletions against conversations. Locate the AI:X stdRuntime.GetVars prototype on the unmerged codex/std-runtime-locals branch; record it separately without adding its implementation to this PR (#191).
- 2026-11-11 `AI documentation` NOTE - Rewrite module AI descriptions as direct declarations of AI use and component scope; keep retrospective research details in the provenance audit. Classifications and dates are unchanged (#191).
37 changes: 37 additions & 0 deletions contribution.md
Original file line number Diff line number Diff line change
Expand Up @@ -132,6 +132,43 @@ End Type
Private This as TThis
```

## Module-level AI disclosure

Document AI involvement using the [0rwx framework](https://0rwx.com/) in the existing module-level documentation block of each new or changed class/module:

```vb
'@module
'@description Describe the class or module here.
'@ai AI:W
'@aidate 2026-10-31
'@aidesc AI was used to add timeout handling, which was reviewed manually. The original transport implementation was written without AI.
```

Use one `@ai` mark when its classification is established:

- `AI:0`: handmade; AI has neither read nor written the work.
- `AI:R`: AI-inspired; AI has read-only access and a human writes the code.
- `AI:W`: AI collaboration; AI writes code that a human reads and scrutinises.
- `AI:X`: AI-made; a human curates output without being able to scrutinise all generated work.

These marks describe involvement and scrutiny, not percentages or a quality rating. A small AI-written fix does not make the entire class AI-made. For mixed provenance, describe the affected component and the older/upstream work in `@aidesc`. A maintainer may classify a module `AI:W` overall while identifying a specific component as `AI:X`; do not automatically elevate the entire module or attribute its older/upstream code to AI. Do not reset known involvement simply because the latest edit was manual.

- `@aidate YYYY-MM-DD` records the earliest evidenced AI involvement in the class/module described by `@aidesc`, including historical experimental versions when relevant. State when that work is absent from the current implementation. Use an actual edit timestamp where available, otherwise a matched commit date; record the basis and uncertainty in a remark or provenance audit. This is a first known date, not proof that no earlier AI use occurred. Do not advance it for follow-up changes. Omit it for `AI:0` or when no date can be established.
- `@aidesc <description>` declares where AI was used, which parts were written without AI or come from upstream authors, and whether the work was reviewed manually. Write direct statements such as "AI was used to add timeout handling" or "The thunk engine was generated entirely by AI (AI:X)." Keep retrospective research methods, commit tracing and uncertainty in the provenance audit rather than phrases such as "by this evidence" or "confirmed by the maintainer" in module descriptions. Preserve existing descriptions, examples, attributions and member documentation.

For retrospective disclosures, cross-check source comments, `git blame`, dated commit diffs and conversation records. Check deletions as well as surviving lines; a deleted line will not appear in blame. Copied upstream code and unmerged experiments must not be counted as AI-generated current implementation. Dates, model names and commit frequency can guide investigation but cannot establish human scrutiny. A CI bot or the absence of an AI co-author is not evidence of authorship either way.

Do not use `AI:X` as a fallback for unknown review history, or infer `AI:W` merely because a fix is small. Where AI authorship is established but W/X is unresolved, retain `@aidate` and `@aidesc` and leave `@ai` absent until the classification can be supported. Do not invent a fifth mark or infer `AI:0` merely from missing attribution. An explicit maintainer declaration can establish the classification.

The maintainer has declared the remaining source modules `AI:0`. Their module documentation uses this wording, without an invented `@aidate`:

```vb
'@ai AI:0
'@aidesc AI has not touched this code yet. This may change to AI:W when AI edits this file.
```

When AI changes an implementation, update its mark, first-evidenced date and scoped description to reflect the contribution and human scrutiny. A disclosure-only edit does not itself establish AI authorship of the implementation. Use each tag at most once per module and regenerate `docs.json` after changing documented source. The generator exposes these as optional `ai`, `aiDate` and `aiDescription` module fields.

## Function-level documentation

A critical area which I am developing is the documentation. All methods should be documented using a `JSDoc`-like equivalent. Docs are analysed by `./Tools/VBDocsGen` (which later will be run on a github action).
Expand Down
Loading
Loading