bugfix/10 facets changes enablement are not reflected in archive #11
Conversation
karmaniverous
commented
Dec 29, 2025
karmaniverous
commented
- [10] docs: clarify facets flags and diff anchors
- [10] fix: facet flags + diff anchors; add regressions
- [10] Fix facets parse test lint + assertion
- [10] Update dev plan after green lint/test
- [10] Add diff anchor changed-only integration test
- [10] Add TypeDoc comments for exported types
- [10] docs(typedoc): export ScriptObject type
- [10] renamed docs-src -> guides
- [10] docs: add stan assistant guide
- [10] docs: refresh guides and cross-links
- [10] updated typedoc
When: 2025-12-29
Why: Commander parsing shows -FS is treated as -F S when -F accepts
optional args, and --no-facets is stored as facets=false (source=cli),
causing overlay enablement and script selection to misbehave.
What changed:
- .stan/system/stan.requirements.md: update facet flag semantics (boolean
-f/-F + explicit --facets-on/off), define explicit-wins ramp-up rule, and
require DIFF to honor anchors while remaining changed-only.
- .stan/system/stan.todo.md: add concrete implementation plan for fixing
flag parsing, overlay resolution, and diff anchor behavior with tests/docs.
When: 2025-12-29T00:00:00Z
Why: Commander option bundling and negation shape caused -FS and --no-facets
to behave incorrectly, and DIFF archives were not honoring anchors.
What changed:
- src/cli/run/options.ts: make -f/-F boolean-only; add --facets-on/off flags
and conflict rules
- src/cli/run/action/overlay-flow.ts: correctly interpret --no-facets as
opts.facets=false with source=cli; wire facets-on/off overrides
- src/cli/run/action/overlay.ts: map overlay excludes only when overlay enabled
- src/runner/overlay/facets.ts: Option Y (explicit off wins) and anchor
.docs.meta.json
- src/runner/overlay/facets.test.ts: update expectations; add explicit-off test
- src/runner/run/session/archive-stage/config.ts (+test): pass anchors into DIFF
- src/cli/run/facets.flags.parse.test.ts: regressions for -FS and --no-facets
- docs-src/*: update docs to match new facet flags and diff anchor policy
- .stan/system/stan.todo.md: record completed work and remaining follow-through
When: 2025-12-29T00:00:00Z
Why: Lint fails due to unsafe any/require-await in facets flag regression test,
and the test expected an outdated plan-only message string.
What changed:
- src/cli/run/facets.flags.parse.test.ts: remove async-without-await mocks,
eliminate any/unsafe calls by typing makeCli() as Commander Command, and
accept current "no scripts selected" plan-only message.
- .stan/system/stan.todo.md: update Next up and append an amendment entry.
When: 2025-12-29T00:00:00Z
Why: All checks are now passing; the plan should reflect the new baseline
and focus on remaining docs/coverage follow-ups.
What changed:
- .stan/system/stan.todo.md: remove stale “fix lint/test fallout” and
“tsdoc warning spam” next steps; append completion note.
When: 2025-12-29T00:00:00Z
Why: We need a regression that proves anchors are honored by DIFF without
breaking the “changed-only vs snapshot” contract, including for
gitignored-but-important state like facet.state.json.
What changed:
- src/runner/run/archive/diff.anchors.changed-only.integration.test.ts:
add an integration test that parses archive.diff.tar entries and asserts
anchored gitignored files appear only when changed vs the snapshot.
- .stan/system/stan.todo.md: record completion and update next steps.
When: 2025-12-29T00:00:00Z
Why: typedoc is configured with validation.notDocumented=true and currently
warns on several exported types/properties in the public API.
What changed:
- src/cli/config/schema.ts: document ScriptEntry/ScriptObject/ScriptMap so
typedoc does not emit "not documented" warnings for script config types.
- src/runner/run/types.ts: document RunnerConfig and RunBehavior and their
properties so typedoc output is clean.
- .stan/system/stan.todo.md: append completion entry for this docs cleanup.
Why: Typedoc warned that ScriptObject is referenced by ScriptEntry but not included in the generated documentation. What changed: - src/index.ts: re-export ScriptObject alongside ScriptEntry/ScriptMap - .stan/system/stan.todo.md: append Completed note for the docs fix
When: 2025-12-29
Why: Provide a self-contained integration/usage contract for STAN assistants
per the repository policy.
What changed:
- guides/stan-assistant-guide.md: new assistant-facing usage guide
- .stan/system/stan.todo.md: append completed entry for the guide
When: 2025-12-29
Why: Bring documentation in line with current CLI behavior and
namespaced configuration; improve navigation with cross-links.
What changed:
- README.md: fix LICENSE link, add FAQ/bootloader links, clarify filenames
- contributing.md: fix clone directory name
- guides/*: align config examples, patch diagnostics, and cross-link guides
- guides/bootloader.md: new bootloader/assistant setup guide
- typedoc.json: include missing guide documents
- .stan/system/stan.todo.md: log documentation pass
There was a problem hiding this comment.
Pull request overview
This PR fixes bug #10 where facet changes were not properly reflected in archives. The changes introduce a breaking redesign of the facet CLI flags to improve clarity and correctness, ensure diff archives honor anchors with changed-only semantics, and add comprehensive documentation and test coverage.
Key changes:
- Breaking change: Facet flags now use
-f/--facetsand-F/--no-facetsas boolean toggles (no arguments), with new--facets-on <names...>and--facets-off <names...>flags for per-run overrides - Diff archives now properly honor anchors with changed-only semantics (anchored files only appear when changed vs snapshot)
- Added "Option Y" logic: explicit per-run deactivations (
--facets-off) prevent auto-suspension safety checks - Documentation reorganization: renamed
docs-src/toguides/and added comprehensive cross-linking and new assistant guide
Reviewed changes
Copilot reviewed 40 out of 43 changed files in this pull request and generated no comments.
Show a summary per file
| File | Description |
|---|---|
| typedoc.json | Updated project documents paths from docs-src/ to guides/, added new guide files, enabled notDocumented validation |
| tsdoc.json | Removed unused @jsx tag definition |
| stan.config.yml | Changed default facets: false, updated lint script to object form with warnPattern, simplified imports |
| src/runner/snap/context.ts | Code formatting cleanup (multiline import statement) |
| src/runner/run/types.ts | Added comprehensive TypeDoc comments for exported types (RunnerConfig, RunBehavior) |
| src/runner/run/session/archive-stage/config.ts | Added anchors field to diff config so diff archives honor anchors (changed-only via snapshot) |
| src/runner/run/session/archive-stage/config.test.ts | New test verifying anchors are passed through to both full and diff configs |
| src/runner/run/archive/diff.anchors.changed-only.integration.test.ts | New integration test proving anchored gitignored files only appear in diff when changed |
| src/runner/overlay/facets.ts | Added explicit per-run deactivation tracking and Option Y logic (no auto-suspend for explicit --facets-off), anchored .docs.meta.json |
| src/runner/overlay/facets.test.ts | Updated tests for new .docs.meta.json anchor and added test for explicit deactivation behavior |
| src/index.ts | Added ScriptObject to exports for complete TypeDoc documentation |
| src/cli/run/options.ts | Breaking change: redesigned facet flags to boolean toggles with separate --facets-on/--facets-off override flags |
| src/cli/run/facets.flags.parse.test.ts | New tests for -FS flag parsing and --no-facets overlay disablement |
| src/cli/run/action/scripts.ts | Code formatting cleanup (multiline import statement) |
| src/cli/run/action/overlay.ts | Simplified overlay mapping logic (removed complex conditional that's no longer needed) |
| src/cli/run/action/overlay-flow.ts | Refactored to handle new boolean facet flags with separate per-run override options |
| src/cli/config/schema.ts | Added comprehensive TypeDoc comments for ScriptObject, ScriptEntry, and ScriptMap types |
| package.json | Updated dependencies including stan-core to ^0.4.7 and various dev dependencies |
| guides/ (multiple files) | Renamed from docs-src/, updated documentation to reflect facet flag changes, added cross-links, added new assistant guide |
| docs-src/ (multiple files) | Deleted old documentation directory (renamed to guides/) |
| .stan/system/stan.todo.md | Updated development plan reflecting completed work |
| .stan/system/stan.requirements.md | Updated requirements to document new facet flag behavior and diff anchor policy |
| .stan/system/facet.meta.json | Updated docs facet to use guides/** instead of docs-src/** |
| .stan/imports/stan-core/ | Updated imported stan-core documentation |
| contributing.md | Fixed typo: cd stan → cd stan-cli |
| README.md | Updated documentation links from docs-src/ to guides/, fixed LICENSE link from LICENSE.md to LICENSE |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Summary of ChangesHello @karmaniverous, I'm Gemini Code Assist1! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed! This pull request delivers a crucial bugfix related to how facet enablement changes are reflected in archives, alongside a significant overhaul of the CLI's facet flag system. It introduces a refined diff archive anchor policy, ensuring that important, often-ignored files are correctly included in diffs when modified. Complementing these functional changes, the project's documentation has undergone a major restructuring and expansion, providing clearer guidance for users and AI assistants alike. These updates collectively enhance the reliability, clarity, and maintainability of the system. Highlights
Using Gemini Code AssistThe full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips. Invoking Gemini You can request assistance from Gemini at any point by creating a comment using either
Customization To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a Limitations & Feedback Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here. You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension. Footnotes
|
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
This pull request introduces a significant and valuable set of changes. The core bugfix, which ensures facet changes and anchors are correctly reflected in diff archives, is well-implemented and tested. The accompanying breaking change to the facet CLI flags is clearly documented, and the new flags provide a more explicit and less ambiguous user experience. The extensive documentation overhaul, including the move from docs-src to guides and the addition of new, detailed guides, greatly improves the project's usability and maintainability. The code is cleaner with added TSDoc comments and new tests that cover the new logic and prevent regressions. Overall, this is a high-quality contribution. I have a couple of minor suggestions for documentation cleanup.
| - Add integration test proving anchored gitignored state appears in diff only when changed vs snapshot. | ||
| - Add missing TypeDoc comments for exported config/run types (silence `notDocumented` warnings). | ||
| - Export `ScriptObject` from `src/index.ts` so TypeDoc includes it when documenting `ScriptEntry`. | ||
| - Add `guides/stan-assistant-guide.md` (assistant integration guide).- Documentation pass: align guides with namespaced config, diagnostics, and add cross-links. |
There was a problem hiding this comment.
It looks like there might be a formatting issue on this line, possibly from a copy-paste. The ).- part and the trailing \ No newline at end of file text seem unintentional. I'd suggest splitting this into two separate list items for clarity.
| - Add `guides/stan-assistant-guide.md` (assistant integration guide).- Documentation pass: align guides with namespaced config, diagnostics, and add cross-links. | |
| - Add `guides/stan-assistant-guide.md` (assistant integration guide). | |
| - Documentation pass: align guides with namespaced config, diagnostics, and add cross-links. |
| # STAN — STAN Tames Autoregressive Nonsense | ||
|
|
||
| [](https://www.npmjs.com/package/@karmaniverous/stan-cli)  <!-- TYPEDOC_EXCLUDE --> [](https://docs.karmanivero.us/stan) [](https://github.com/karmaniverous/stan-cli/tree/main/CHANGELOG.md)<!-- /TYPEDOC_EXCLUDE --> [](https://github.com/karmaniverous/stan-cli/tree/main/LICENSE.md) | ||
| [](https://www.npmjs.com/package/@karmaniverous/stan-cli)  <!-- TYPEDOC_EXCLUDE --> [](https://docs.karmanivero.us/stan) [](https://github.com/karmaniverous/stan-cli/tree/main/CHANGELOG.md)<!-- /TYPEDOC_EXCLUDE --> [](https://github.com/karmaniverous/stan-cli/tree/main/LICENSE) |
There was a problem hiding this comment.
The link to the license file appears to have been broken in this change. It was modified from LICENSE.md to LICENSE. Please verify the correct filename and update the link accordingly. It's likely it should be LICENSE.md.
| [](https://www.npmjs.com/package/@karmaniverous/stan-cli)  <!-- TYPEDOC_EXCLUDE --> [](https://docs.karmanivero.us/stan) [](https://github.com/karmaniverous/stan-cli/tree/main/CHANGELOG.md)<!-- /TYPEDOC_EXCLUDE --> [](https://github.com/karmaniverous/stan-cli/tree/main/LICENSE) | |
| [](https://www.npmjs.com/package/@karmaniverous/stan-cli)  <!-- TYPEDOC_EXCLUDE --> [](https://docs.karmanivero.us/stan) [](https://github.com/karmaniverous/stan-cli/tree/main/CHANGELOG.md)<!-- /TYPEDOC_EXCLUDE --> [](https://github.com/karmaniverous/stan-cli/tree/main/LICENSE.md) |
| ```bash | ||
| git clone https://github.com/karmaniverous/stan-cli.git | ||
| cd stan | ||
| cd stan-cli |
There was a problem hiding this comment.
This is a great fix! Correcting the directory path in the setup instructions is crucial for a smooth onboarding experience for new contributors.
| /** Build FULL and DIFF base configs; DIFF honors anchors (changed-only via snapshot). */ | ||
| export const makeBaseConfigs = ( | ||
| config: RunnerConfig, | ||
| ): { |
There was a problem hiding this comment.
This change to include anchors in the diff configuration is the core of the bugfix and correctly addresses the issue of facet changes not being reflected in the diff archive. The updated comment also clearly reflects the new behavior. Excellent work.
